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

Artigo
04/07/2024

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

Se seu aplicativo for executado no Azure Service Fabric, Serviços de Nuvem do Azure, Máquinas Virtuais do Azure ou máquinas locais, você poderá ignorar a habilitação do Depurador de Instantâneo no Serviço de Aplicativo e seguir as orientações neste artigo.

Antes de começar

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

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

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

Se você não vir SnapshotCollectorTelemetryProcessor em ApplicationInsights.config, ou se quiser personalizar a configuração do Depurador de Instantâneo, poderá editá-la manualmente. No entanto, essas edições podem 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 somente em exceções relatadas ao Application Insights. Em alguns casos (por exemplo, versões mais antigas da plataforma .NET), talvez seja necessário configurar a coleta de exceções para ver exceções com instantâneos no portal.

Configurar a coleta de instantâneos para aplicativos ASP.NET Core ou Worker Services

Pré-requisitos

Seu aplicativo já deve fazer referência a um dos seguintes pacotes NuGet do Application Insights:

Adicionar o pacote NuGet

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

Atualizar a coleção de serviços

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

var builder = WebApplication.CreateBuilder(args);

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

Configurar o coletor de instantâneo

Para a maioria das situações, as configurações padrão são suficientes. Caso contrário, personalize as configurações adicionando o seguinte código antes da chamada para AddSnapshotCollector()

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

Em seguida, adicione uma SnapshotCollector seção ao appsettings.json onde 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 leva um delegado. Por exemplo:

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

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

Os instantâneos são coletados somente em exceções relatadas ao Application Insights. Para aplicativos ASP.NET e ASP.NET Core, o SDK do Application Insights relata automaticamente exceções não tratadas que escapam de um método de controlador ou manipulador de rota de ponto de extremidade. Para outros aplicativos, talvez seja necessário modificar seu código para relatá-los. O código de tratamento de exceção depende da estrutura do seu aplicativo. Eis 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 exemplo a seguir usa ILogger em vez de TelemetryClient. Este exemplo pressupõe que você esteja usando o Application Insights Logger Provider. Como mostra o exemplo, ao manipular uma exceção, certifique-se 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.");
    }
  }
}

Nota

Por padrão, o Application Insights Logger (ApplicationInsightsLoggerProvider) encaminha exceções para o Depurador de Instantâneo via TelemetryClient.TrackException. Esse comportamento é controlado por meio da TrackExceptionsAsExceptionTelemetry propriedade na ApplicationInsightsLoggerOptions classe. Se você definir TrackExceptionsAsExceptionTelemetry como ao false configurar o Application Insights Logger, o exemplo anterior não acionará o Depurador de Instantâneo. Nesse caso, modifique seu código para chamar TrackException manualmente.