Compartir vía

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

  • Artículo

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.

Requisitos previos

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

Al agregar el paquete NuGet de Microsoft.ApplicationInsights.SnapshotCollector a la aplicación, el SnapshotCollectorTelemetryProcessor se agrega 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.

Nota:

Las configuraciones manuales se pueden sobrescribir al actualizar a una versión más reciente del paquete NuGet Microsoft.ApplicationInsights.SnapshotCollector.

La configuración predeterminada de Snapshot Collector es similar al ejemplo siguiente:

<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. Se recomienda 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();

Personalizar Snapshot Collector

En la mayoría de los escenarios, la configuración predeterminada de Snapshot Collector es suficiente. Sin embargo, puede personalizar la configuración agregando el código siguiente antes de la llamada a AddSnapshotCollector():

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

A continuación, agregue una sección de SnapshotCollector a appsettings.json donde puede invalidar los valores predeterminados.

La configuración predeterminada de Snapshot Collector appsettings.json tiene un aspecto similar al ejemplo siguiente:

{
  "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. Por 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.");
    }
  }
}

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 establece 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.

Nota:

El 31 de marzo de 2025 finalizará la compatibilidad con la ingesta de claves de instrumentación. La ingesta de claves de instrumentación seguirá funcionando, pero la característica ya no recibirá actualizaciones ni soporte técnico. Transición a las cadenas de conexión para aprovechar las nuevas funcionalidades.

Pasos siguientes