Habilitar o Depurador de Instantâneos para aplicativos .NET no Azure Service Fabric, Serviços de Nuvem e Máquinas Virtuais

Se o aplicativo ASP.NET ou ASP.NET Core for executado em Serviço de Aplicativo do Azure e exigir uma configuração personalizada do Depurador de Instantâneos ou uma versão prévia do .NET Core, comece com o Habilitar Depurador de Instantâneos para aplicativos .NET no Serviço de Aplicativo do Azure.

Se o aplicativo for executado no Azure Service Fabric, nos Serviços de Nuvem do Azure, em Máquinas Virtuais do Azure ou em computadores locais, você poderá ignorar a habilitação do Depurador de Instantâneos no Serviço de Aplicativo e seguir as diretrizes deste artigo.

Pré-requisitos

• Habilite o Application Insights em seu recurso .NET.
• Inclua o pacote NuGet Microsoft.ApplicationInsights.SnapshotCollector versão 1.4.2 ou superior no seu aplicativo.
• Entenda que os instantâneos podem levar de 10 a 15 minutos para serem enviados para a instância do Application Insights depois que uma exceção for disparada.

Configurar a coleta de instantâneo para aplicativos ASP.NET

Ao adicionar o pacote NuGet Microsoft.ApplicationInsights.SnapshotCollector ao aplicativo, o SnapshotCollectorTelemetryProcessor é adicionado automaticamente à TelemetryProcessors na seção de ApplicationInsights.config.

Caso não visualize SnapshotCollectorTelemetryProcessor em ApplicationInsights.config ou queira personalizar a configuração do Depurador de Instantâneos, poderá editá-la manualmente.

A configuração padrão do Snapshot Collector é semelhante ao exemplo a seguir:

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

Os instantâneos são coletados apenas em exceções relatadas ao Application Insights. Em alguns casos (por exemplo, versões mais antigas da plataforma .NET), talvez seja necessário configurar coleta de exceção para ver exceções com instantâneos no portal.

Configurar coleção de instantâneo para aplicativos ASP.NET Core ou Serviços de Trabalho

Pré-requisitos

Seu aplicativo já deve referenciar um dos seguintes pacotes NuGet do Application Insights:

• Microsoft.ApplicationInsights.AspNetCore
• Microsoft.ApplicationInsights.WorkerService

Adicionar o pacote NuGet

Adicione o pacote NuGet Microsoft.ApplicationInsights.SnapshotCollector em seu aplicativo.

Atualizar a coleção de serviços

No código de inicialização do aplicativo, onde os serviços estão configurados, adicione uma chamada ao método de extensão AddSnapshotCollector. Sugerimos adicionar essa linha imediatamente após a chamada para AddApplicationInsightsTelemetry. Por exemplo:

var builder = WebApplication.CreateBuilder(args);

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

Personalizar o Snapshot Collector

Para a maioria dos cenários, as configurações padrão do Snapshot Collector são suficientes. No entanto, você poderá personalizar as configurações adicionando o código a seguir antes da chamada para AddSnapshotCollector():

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

Em seguida, adicione uma seção SnapshotCollector ao appsettings.json onde você poderá substituir os padrões.

A configuração padrão appsettings.json do Snapshot Collector é semelhante ao exemplo a seguir:

{
  "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
  }
}

Se você precisar personalizar o comportamento do Snapshot Collector manualmente, sem usar appsettings.json, use a sobrecarga de AddSnapshotCollector que usa um delegado. Por exemplo:

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

Configurar a coleta de instantâneo para outros aplicativos .NET

Os instantâneos são coletados apenas em exceções que são relatadas ao Application Insights.

Para aplicativos ASP.NET e ASP.NET Core, o SDK do Application Insights relata automaticamente exceções sem tratamento que escapam a um método de controlador ou manipulador de rotas de ponto de extremidade.

Para outros aplicativos, talvez seja necessário modificar seu código para denunciá-los. O código de tratamento de exceção depende da estrutura do seu aplicativo. Por exemplo:

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

O seguinte exemplo usa ILogger em vez de TelemetryClient. Este exemplo pressupõe que você esteja usando o Provedor de Agente do Application Insights. Como mostra o exemplo, ao lidar com uma exceção, não deixe de passar a exceção como o primeiro parâmetro para 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.");
    }
  }
}

Por padrão, o Agente do Application Insights (ApplicationInsightsLoggerProvider) encaminha exceções para o Depurador de Instantâneos por TelemetryClient.TrackException. Esse comportamento é controlado por meio da propriedade TrackExceptionsAsExceptionTelemetry na classe ApplicationInsightsLoggerOptions.

Caso defina TrackExceptionsAsExceptionTelemetry como false ao configurar o Agente do Application Insights, o exemplo anterior não vai disparar o Depurador de Instantâneos. Nesse caso, modifique seu código para chamar TrackException manualmente.

Próximas etapas

• Exiba instantâneos no portal do Azure.
• Solucione problemas do Depurador de Instantâneos.