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

Artigo
04/09/2024

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.

Antes de começar

Habilitar o Application Insights no aplicativo Web.
Inclua o pacote NuGet Microsoft.ApplicationInsights.SnapshotCollector versão 1.4.2 ou superior no seu aplicativo.

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

Quando você adiciona o pacote NuGet Microsoft.ApplicationInsights.SnapshotCollector ao seu aplicativo, o SnapshotCollectorTelemetryProcessor deve ser adicionado automaticamente à seção TelemetryProcessors de ApplicationInsights.config.

Se você não vir SnapshotCollectorTelemetryProcessor no ApplicationInsights.config ou se quiser personalizar a configuração do Depurador de Instantâneos, poderá editá-la manualmente. No entanto, essas edições poderão ser substituídas se você atualizar posteriormente para uma versão mais recente do pacote NuGet Microsoft.ApplicationInsights.SnapshotCollector.

O exemplo a seguir mostra uma configuração equivalente à configuração padrão:

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

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. É uma boa ideia 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();

Configurar o Snapshot Collector

Na maioria dos casos, as configurações padrão são suficientes. Caso contrário, personalize 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 a appsettings.json em que você pode substituir os padrões. O exemplo a seguir mostra uma configuração equivalente à configuração padrão:

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

Observação

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. Se você definir 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.