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

Se l'applicazione ASP.NET o ASP.NET Core viene eseguita in Servizio app di 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 in Servizio app di Azure.

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

Prerequisiti

• Abilitare Application Insights nella risorsa .NET.
• Includere il pacchetto NuGet Microsoft.ApplicationInsights.SnapshotCollector, versione 1.4.2 o successiva, nell'app.
• Tenere conto che l’invio degli snapshot all'istanza di Application Insights può richiedere da 10 a 15 minuti dopo l'attivazione di un'eccezione.

Configurare la raccolta di snapshot per le applicazioni ASP.NET

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

Se non viene visualizzato SnapshotCollectorTelemetryProcessor in ApplicationInsights.config o si vuole personalizzare la configurazione di Snapshot Debugger, è possibile modificarla manualmente.

La configurazione predefinita di Snapshot Collector è simile all'esempio seguente:

<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 per le 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 le applicazioni ASP.NET Core o i servizi del ruolo di lavoro

Prerequisiti

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

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

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 metodo di estensione AddSnapshotCollector. È consigliabile aggiungere questa riga immediatamente dopo la chiamata a AddApplicationInsightsTelemetry. Ad esempio:

var builder = WebApplication.CreateBuilder(args);

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

Personalizzare Snapshot Collector

Le impostazioni predefinite di Snapshot Collector sono sufficienti per la maggior parte degli scenari. Tuttavia, è possibile 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 sezione SnapshotCollector a appsettings.json in cui è possibile eseguire l'override delle impostazioni predefinite.

La configurazione predefinita appsettings.json di Snapshot Collector è simile all'esempio seguente:

{
  "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 di Snapshot Collector, 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 le 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 segnalarle. Il codice di gestione delle eccezioni dipende dalla struttura dell'applicazione. Ad 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 usato ILogger anziché TelemetryClient. In questo esempio si presuppone che si stia usando il provider del 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.");
    }
  }
}

Per impostazione predefinita, il logger di Application Insights (ApplicationInsightsLoggerProvider) inoltra le eccezioni a Snapshot Debugger tramite TelemetryClient.TrackException. Questo comportamento viene controllato tramite la proprietà TrackExceptionsAsExceptionTelemetry nella classe ApplicationInsightsLoggerOptions.

Se si imposta TrackExceptionsAsExceptionTelemetry su false durante la configurazione del logger di Application Insights, l'esempio precedente non attiverà Snapshot Debugger. In questo caso, modificare il codice per chiamare TrackException manualmente.

Passaggi successivi

• Visualizzare gli snapshot nel portale di Azure.
• Risolvere i problemi relativi a Snapshot Debugger.