Compartilhar via

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

  • Artigo

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

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.

Observação

Qualquer configuração manual pode ser substituída ao atualizar para uma versão mais recente do pacote NuGet Microsoft.ApplicationInsights.SnapshotCollector.

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 (como em 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 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 ao 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 do appsettings.json do Coletor de Instantâneos é 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.

Observação

Em 31 de março de 31, 2025, o suporte à ingestão de chave de instrumentação será encerrado. A ingestão de chave de instrumentação continuará funcionando, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar as novas funcionalidades.

Próximas etapas