Habilitar Snapshot Debugger para aplicaciones .NET en Azure Service Fabric, Cloud Services y Virtual Machines

Artículo
04/11/2024

Si la aplicación de ASP.NET o ASP.NET Core se ejecuta en Azure App Service y requiere una configuración personalizada de Snapshot Debugger o una versión preliminar de .NET Core, comience con Habilitación de Snapshot Debugger para aplicaciones .NET en Azure App Service.

Si la aplicación se ejecuta en Azure Service Fabric, Azure Cloud Services, Azure Virtual Machines o máquinas locales, puede omitir la habilitación de Snapshot Debugger en App Service y seguir la guía de este artículo.

Antes de empezar

Habilite Application Insights en la aplicación web.
Incluya el paquete NuGet Microsoft.ApplicationInsights.SnapshotCollector, versión 1.4.2 o posterior, en la aplicación.

Configurar la recopilación de instantáneas para aplicaciones ASP.NET

Al agregar el paquete NuGet Microsoft.ApplicationInsights.SnapshotCollector a la aplicación, SnapshotCollectorTelemetryProcessor se debe agregar automáticamente a la sección TelemetryProcessors de ApplicationInsights.config.

Si no ve SnapshotCollectorTelemetryProcessor en ApplicationInsights.config, o si desea personalizar la configuración de Snapshot Debugger, puede editarla manualmente. Sin embargo, estas modificaciones se pueden sobrescribir si posteriormente actualiza a una versión más reciente del paquete NuGet Microsoft.ApplicationInsights.SnapshotCollector.

En el ejemplo siguiente se muestra una configuración equivalente a la configuración predeterminada:

<TelemetryProcessors>
  <Add Type="Microsoft.ApplicationInsights.SnapshotCollector.SnapshotCollectorTelemetryProcessor, Microsoft.ApplicationInsights.SnapshotCollector">
    <!-- The default is true, but you can disable Snapshot Debugging by setting it to false -->
    <IsEnabled>true</IsEnabled>
    <!-- Snapshot Debugging is usually disabled in developer mode, but you can enable it by setting this to true. -->
    <!-- DeveloperMode is a property on the active TelemetryChannel. -->
    <IsEnabledInDeveloperMode>false</IsEnabledInDeveloperMode>
    <!-- How many times we need to see an exception before we ask for snapshots. -->
    <ThresholdForSnapshotting>1</ThresholdForSnapshotting>
    <!-- The maximum number of examples we create for a single problem. -->
    <MaximumSnapshotsRequired>3</MaximumSnapshotsRequired>
    <!-- The maximum number of problems that we can be tracking at any time. -->
    <MaximumCollectionPlanSize>50</MaximumCollectionPlanSize>
    <!-- How often we reconnect to the stamp. The default value is 15 minutes.-->
    <ReconnectInterval>00:15:00</ReconnectInterval>
    <!-- How often to reset problem counters. -->
    <ProblemCounterResetInterval>1.00:00:00</ProblemCounterResetInterval>
    <!-- The maximum number of snapshots allowed in ten minutes.The default value is 1. -->
    <SnapshotsPerTenMinutesLimit>3</SnapshotsPerTenMinutesLimit>
    <!-- The maximum number of snapshots allowed per day. -->
    <SnapshotsPerDayLimit>30</SnapshotsPerDayLimit>
    <!-- Whether or not to collect snapshot in low IO priority thread. The default value is true. -->
    <SnapshotInLowPriorityThread>true</SnapshotInLowPriorityThread>
    <!-- Agree to send anonymous data to Microsoft to make this product better. -->
    <ProvideAnonymousTelemetry>true</ProvideAnonymousTelemetry>
    <!-- The limit on the number of failed requests to request snapshots before the telemetry processor is disabled. -->
    <FailedRequestLimit>3</FailedRequestLimit>
  </Add>
</TelemetryProcessors>

Las instantáneas solo se recopilan en las excepciones que se informan a Application Insights. En algunos casos (por ejemplo, en versiones anteriores de la plataforma. NET), es posible que tenga que configurar la recopilación de excepciones para ver las excepciones con las instantáneas en el portal.

Configuración de la recopilación de instantáneas para aplicaciones ASP.NET Core o Servicios de trabajo

Requisitos previos

La aplicación ya debe hacer referencia a uno de los siguientes paquetes NuGet de Application Insights:

Incorporación del paquete NuGet

Agregue el paquete NuGet Microsoft.ApplicationInsights.SnapshotCollector a la aplicación.

Actualización de la colección de servicios

En el código de inicio de la aplicación, donde se configuran los servicios, agregue una llamada al método de extensión AddSnapshotCollector. Es recomendable agregar esta línea inmediatamente después de la llamada a AddApplicationInsightsTelemetry. Por ejemplo:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddSnapshotCollector();

Configuración de Snapshot Collector

La configuración predeterminada suele ser suficiente para la mayoría de las situaciones. De no serlo, puede agregar el código siguiente antes de la llamada a AddSnapshotCollector() para personalizar la configuración

using Microsoft.ApplicationInsights.SnapshotCollector;
...
builder.Services.Configure<SnapshotCollectorConfiguration>(builder.Configuration.GetSection("SnapshotCollector"));

A continuación, agregue una sección SnapshotCollector a appsettings.json, donde puede invalidar los valores predeterminados. En el ejemplo siguiente se muestra una configuración equivalente a la configuración predeterminada:

{
  "SnapshotCollector": {
    "IsEnabledInDeveloperMode": false,
    "ThresholdForSnapshotting": 1,
    "MaximumSnapshotsRequired": 3,
    "MaximumCollectionPlanSize": 50,
    "ReconnectInterval": "00:15:00",
    "ProblemCounterResetInterval":"1.00:00:00",
    "SnapshotsPerTenMinutesLimit": 1,
    "SnapshotsPerDayLimit": 30,
    "SnapshotInLowPriorityThread": true,
    "ProvideAnonymousTelemetry": true,
    "FailedRequestLimit": 3
  }
}

Si necesita personalizar manualmente el comportamiento de Snapshot Collector, sin usar appsettings.json, use la sobrecarga de AddSnapshotCollector que toma un delegado. Por ejemplo:

builder.Services.AddSnapshotCollector(config => config.IsEnabledInDeveloperMode = true);

Configurar la recopilación de instantáneas para otras aplicaciones .NET

Las instantáneas solo se recopilan en las excepciones de las que se informa a Application Insights. Para las aplicaciones ASP.NET y ASP.NET Core, el SDK de Application Insights informa automáticamente de excepciones no controladas que escapan de un método de controlador o controlador de ruta de punto de conexión. En el caso de otras aplicaciones, es posible que tenga que modificar el código para enviar informes. El código de control de excepciones depende de la estructura de la aplicación. Este es un ejemplo:

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;

internal class ExampleService
{
  private readonly TelemetryClient _telemetryClient;

  public ExampleService(TelemetryClient telemetryClient)
  {
    // Obtain the TelemetryClient via dependency injection.
    _telemetryClient = telemetryClient;
  }

  public void HandleExampleRequest()
  {
    using IOperationHolder<RequestTelemetry> operation = 
        _telemetryClient.StartOperation<RequestTelemetry>("Example");
    try
    {
      // TODO: Handle the request.
      operation.Telemetry.Success = true;
    }
    catch (Exception ex)
    {
      // Report the exception to Application Insights.
      operation.Telemetry.Success = false;
      _telemetryClient.TrackException(ex);
      // TODO: Rethrow the exception if desired.
    }
  }
}

En el ejemplo siguiente, se usa ILogger en lugar de TelemetryClient. En este ejemplo se supone que usas el Proveedor del registrador de Application Insights. Como se muestra en el ejemplo, al controlar una excepción, asegúrate de pasar la excepción como primer parámetro a LogError.

using Microsoft.Extensions.Logging;

internal class LoggerExample
{
  private readonly ILogger _logger;

  public LoggerExample(ILogger<LoggerExample> logger)
  {
    _logger = logger;
  }

  public void HandleExampleRequest()
  {
    using IDisposable scope = _logger.BeginScope("Example");
    try
    {
      // TODO: Handle the request
    }
    catch (Exception ex)
    {
      // Use the LogError overload with an Exception as the first parameter.
      _logger.LogError(ex, "An error occurred.");
    }
  }
}

Nota:

De manera predeterminada, el registrador de Application Insights (ApplicationInsightsLoggerProvider) reenvía excepciones a Snapshot Debugger mediante TelemetryClient.TrackException. Este comportamiento se controla mediante la propiedad TrackExceptionsAsExceptionTelemetry de la clase ApplicationInsightsLoggerOptions. Si estableces TrackExceptionsAsExceptionTelemetry en false al configurar el registrador de Application Insights, el ejemplo anterior no desencadenará Snapshot Debugger. En este caso, modifica el código para llamar a TrackException manualmente.