Abilitare Snapshot Debugger per le app .NET in Azure Service Fabric, Servizi cloud e Macchine virtuali

Articolo
04/07/2024

Se l'applicazione ASP.NET o ASP.NET Core viene eseguita nel servizio app Azure e richiede una configurazione personalizzata di Snapshot Debugger o una versione di anteprima di .NET Core, iniziare con Abilitare snapshot debugger per le app .NET nel servizio app Azure.

Se l'applicazione viene eseguita in Azure Service Fabric, Azure Servizi cloud, Azure Macchine virtuali o computer locali, è possibile ignorare l'abilitazione di Snapshot Debugger in servizio app e seguire le indicazioni riportate in questo articolo.

Operazioni preliminari

Abilitare Application Insights nell'app Web.
Includere il pacchetto NuGet Microsoft.ApplicationInsights.SnapshotCollector versione 1.4.2 o successiva nell'app.

Configurare la raccolta di snapshot per le applicazioni ASP.NET

Quando si aggiunge il pacchetto NuGet Microsoft.ApplicationInsights.SnapshotCollector all'applicazione, deve SnapshotCollectorTelemetryProcessor essere aggiunto automaticamente alla TelemetryProcessors sezione di ApplicationInsights.config.

Se non viene visualizzato SnapshotCollectorTelemetryProcessor in ApplicationInsights.config o se si vuole personalizzare la configurazione di Snapshot Debugger, è possibile modificarla a mano. Tuttavia, queste modifiche potrebbero essere sovrascritte se in un secondo momento si esegue l'aggiornamento a una versione più recente del pacchetto NuGet Microsoft.ApplicationInsights.SnapshotCollector .

L'esempio seguente mostra una configurazione equivalente alla configurazione predefinita:

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

Gli snapshot vengono raccolti solo in caso di eccezioni segnalate ad Application Insights. In alcuni casi (ad esempio, versioni precedenti della piattaforma .NET), potrebbe essere necessario configurare la raccolta di eccezioni per visualizzare le eccezioni con gli snapshot nel portale.

Configurare la raccolta di snapshot per ASP.NET applicazioni di base o servizi di lavoro

Prerequisiti

L'applicazione deve già fare riferimento a uno dei pacchetti NuGet di Application Insights seguenti:

Aggiungere il pacchetto NuGet

Aggiungere il pacchetto NuGet Microsoft.ApplicationInsights.SnapshotCollector all'app.

Aggiornare la raccolta di servizi

Nel codice di avvio dell'applicazione, in cui sono configurati i servizi, aggiungere una chiamata al AddSnapshotCollector metodo di estensione. È consigliabile aggiungere questa riga subito dopo la chiamata a AddApplicationInsightsTelemetry. Ad esempio:

var builder = WebApplication.CreateBuilder(args);

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

Configurare l'agente di raccolta snapshot

Per la maggior parte delle situazioni, le impostazioni predefinite sono sufficienti. In caso contrario, personalizzare le impostazioni aggiungendo il codice seguente prima della chiamata a AddSnapshotCollector()

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

Aggiungere quindi una SnapshotCollector sezione a appsettings.json in cui è possibile eseguire l'override delle impostazioni predefinite. L'esempio seguente mostra una configurazione equivalente alla configurazione predefinita:

{
  "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 è necessario personalizzare manualmente il comportamento dell'agente di raccolta snapshot, senza usare appsettings.json, usare l'overload di AddSnapshotCollector che accetta un delegato. Ad esempio:

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

Configurare la raccolta di snapshot per le altre applicazioni .NET

Gli snapshot vengono raccolti solo per le eccezioni segnalate ad Application Insights. Per le applicazioni ASP.NET e ASP.NET Core, Application Insights SDK segnala automaticamente eccezioni non gestite che eseguano l'escape di un metodo controller o di un gestore di route dell'endpoint. Per altre applicazioni, potrebbe essere necessario modificare il codice per segnalarli. Il codice di gestione delle eccezioni dipende dalla struttura dell'applicazione. Ecco un esempio:

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

Nell'esempio seguente viene ILogger usato anziché TelemetryClient. In questo esempio si presuppone che si stia usando il provider Logger di Application Insights. Come illustrato nell'esempio, quando si gestisce un'eccezione, assicurarsi di passare l'eccezione come primo parametro 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.");
    }
  }
}

Nota

Per impostazione predefinita, Application Insights Logger (ApplicationInsightsLoggerProvider) inoltra le eccezioni al debugger snapshot tramite TelemetryClient.TrackException. Questo comportamento viene controllato tramite la TrackExceptionsAsExceptionTelemetry proprietà nella ApplicationInsightsLoggerOptions classe . Se si imposta su TrackExceptionsAsExceptionTelemetryfalse durante la configurazione di Application Insights Logger, l'esempio precedente non attiverà snapshot debugger. In questo caso, modificare il codice per chiamare TrackException manualmente.