Snapshot di debug per le eccezioni nelle app .NET

Quando si verifica un'eccezione, è possibile raccogliere automaticamente uno snapshot di debug dall'applicazione Web live. Lo snapshot mostra lo stato del codice sorgente e delle variabili nel momento in cui è stata generata l'eccezione. Snapshot Debugger (anteprima) di Azure Application Insights monitora la telemetria delle eccezioni dall'app Web. Raccoglie snapshot per le eccezioni generate più frequentemente in modo che l'utente possa avere le informazioni necessarie per diagnosticare i problemi nell'ambiente di produzione. Includere il pacchetto NuGet Snapshot Collector nell'applicazione e configurare facoltativamente i parametri di raccolta in ApplicationInsights.config. Gli snapshot vengono visualizzati per le eccezioni nel portale Application Insights.

È possibile visualizzare gli snapshot di debug nel portale per vedere lo stack di chiamate e ispezionare le variabili in ogni stack frame di chiamate. Per eseguire più efficacemente il debug del codice sorgente, aprire gli snapshot con Visual Studio 2017 Enterprise scaricando l'estensione Snapshot Debugger per Visual Studio.

La raccolta di snapshot è disponibile per:

  • Applicazioni .NET Framework e ASP.NET che eseguono .NET Framework 4.5 o versione successiva.
  • Applicazioni .NET Core 2.0 e ASP.NET Core 2.0 in esecuzione in Windows.

Configurare la raccolta di snapshot per le applicazioni ASP.NET

  1. Abilitare Application Insights nell'app Web se non è ancora stato fatto.

  2. Includere il pacchetto NuGet Microsoft.ApplicationInsights.SnapshotCollector nell'app.

  3. Esaminare le opzioni predefinite che il pacchetto ha aggiunto ad ApplicationInsights.config:

    <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>5</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 to reset problem counters. -->
        <ProblemCounterResetInterval>06:00:00</ProblemCounterResetInterval>
        <!-- The maximum number of snapshots allowed in one minute. -->
        <SnapshotsPerMinuteLimit>2</SnapshotsPerMinuteLimit>
        <!-- The maximum number of snapshots allowed per day. -->
        <SnapshotsPerDayLimit>50</SnapshotsPerDayLimit>
        </Add>
    </TelemetryProcessors>
    
  4. 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 2.0

  1. Abilitare Application Insights nell'app Web ASP.NET Core se non è ancora stato fatto.

  2. Includere il pacchetto NuGet Microsoft.ApplicationInsights.SnapshotCollector nell'app.

  3. Modificare il metodo ConfigureServices nella classe Startup dell'applicazione per aggiungere il processore di telemetria dell'agente di raccolta snapshot. Il codice da aggiungere dipende dalla versione referenziata del pacchetto Microsoft.ApplicationInsights.ASPNETCore NuGet.

    Per Microsoft.ApplicationInsights.AspNetCore 2.1.0 aggiungere:

    using Microsoft.ApplicationInsights.SnapshotCollector;
    ...
    class Startup
    {
        // This method is called by the runtime. Use it to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddSingleton<Func<ITelemetryProcessor, ITelemetryProcessor>>(next => new SnapshotCollectorTelemetryProcessor(next));
            // TODO: Add any other services your application needs here.
        }
    }
    

    Per Microsoft.ApplicationInsights.AspNetCore 2.1.1 aggiungere:

    using Microsoft.ApplicationInsights.SnapshotCollector;
    ...
    class Startup
    {
        private class SnapshotCollectorTelemetryProcessorFactory : ITelemetryProcessorFactory
        {
            public ITelemetryProcessor Create(ITelemetryProcessor next) =>
                new SnapshotCollectorTelemetryProcessor(next);
        }
    
        // This method is called by the runtime. Use it to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
             services.AddSingleton<ITelemetryProcessorFactory>(new SnapshotCollectorTelemetryProcessorFactory());
            // TODO: Add any other services your application needs here.
        }
    }
    

Configurare la raccolta di snapshot per le altre applicazioni .NET

  1. Se l'applicazione non è già instrumentata con Application Insights, iniziare abilitando Application Insights e impostando la chiave di strumentazione.

  2. Aggiungere il pacchetto NuGet Microsoft.ApplicationInsights.SnapshotCollector nell'app.

  3. Gli snapshot vengono raccolti solo per le eccezioni segnalate ad Application Insights. Potrebbe essere necessario modificare il codice per segnalarle. Anche se il codice di gestione delle eccezioni dipende dalla struttura dell'applicazione, di seguito è riportato un esempio:

    TelemetryClient _telemetryClient = new TelemetryClient();
    
    void ExampleRequest()
    {
         try
         {
             // TODO: Handle the request.
         }
         catch (Exception ex)
         {
             // Report the exception to Application Insights.
             _telemetryClient.TrackException(ex);
    
             // TODO: Rethrow the exception if desired.
         }
    }
    
    
    

Grant permissions

Owners of the Azure subscription can inspect snapshots. Other users must be granted permission by an owner.

To grant permission, assign the Application Insights Snapshot Debugger role to users who will inspect snapshots. This role can be assigned to individual users or groups by subscription owners for the target Application Insights resource or its resource group or subscription.

  1. Open the Access Control (IAM) blade.
  2. Click the +Add button.
  3. Select Application Insights Snapshot Debugger from the Roles drop-down list.
  4. Search for and enter a name for the user to add.
  5. Click the Save button to add the user to the role.

[!IMPORTANT] Snapshots can potentially contain personal and other sensitive information in variable and parameter values.

Debug snapshots in the Application Insights portal

If a snapshot is available for a given exception or a problem ID, an Open Debug Snapshot button appears on the exception in the Application Insights portal.

Open Debug Snapshot button on exception

In the Debug Snapshot view, you see a call stack and a variables pane. When you select frames of the call stack in the call stack pane, you can view local variables and parameters for that function call in the variables pane.

View Debug Snapshot in the portal

Snapshots might contain sensitive information, and by default they are not viewable. To view snapshots, you must have the Application Insights Snapshot Debugger role assigned to you.

Debug snapshots with Visual Studio 2017 Enterprise

  1. Click the Download Snapshot button to download a .diagsession file, which can be opened by Visual Studio 2017 Enterprise.

  2. To open the .diagsession file, you must first download and install the Snapshot Debugger extension for Visual Studio.

  3. After you open the snapshot file, the Minidump Debugging page in Visual Studio appears. Click Debug Managed Code to start debugging the snapshot. The snapshot opens to the line of code where the exception was thrown so that you can debug the current state of the process.

    View debug snapshot in Visual Studio

The downloaded snapshot contains any symbol files that were found on your web application server. These symbol files are required to associate snapshot data with source code. For App Service apps, make sure to enable symbol deployment when you publish your web apps.

How snapshots work

When your application starts, a separate snapshot uploader process is created that monitors your application for snapshot requests. When a snapshot is requested, a shadow copy of the running process is made in about 10 to 20 minutes. The shadow process is then analyzed, and a snapshot is created while the main process continues to run and serve traffic to users. The snapshot is then uploaded to Application Insights along with any relevant symbol (.pdb) files that are needed to view the snapshot.

Current limitations

Publish symbols

The Snapshot Debugger requires symbol files on the production server to decode variables and to provide a debugging experience in Visual Studio. The 15.2 release of Visual Studio 2017 publishes symbols for release builds by default when it publishes to App Service. In prior versions, you need to add the following line to your publish profile .pubxml file so that symbols are published in release mode:

    <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

Per Calcolo di Azure e altri tipi di calcoli, verificare che i file di simboli si trovino nella stessa cartella della DLL dell'applicazione principale (generalmente wwwroot/bin) o che siano disponibili nel percorso corrente.

Compilazioni ottimizzate

In alcuni casi le variabili locali non possono essere visualizzate nelle build di versione a causa delle ottimizzazioni applicate durante il processo di compilazione.

Risoluzione dei problemi

Questi suggerimenti consentono di risolvere i problemi relativi al debugger di snapshot.

Verificare la chiave di strumentazione

Verificare di usare la chiave di strumentazione corretta nell'applicazione pubblicata. Application Insights in genere legge la chiave di strumentazione dal file ApplicationInsights.config. Verificare che il valore sia lo stesso della chiave di strumentazione per la risorsa di Application Insights visualizzata nel portale.

Controllare i log dell'utilità di caricamento

Dopo la creazione di uno snapshot, un file di minidump (DMP) viene creato sul disco. Un processo di caricamento separato prende il file di minidump e lo carica, con i file PDB associati, nella risorsa di archiviazione Debugger di snapshot di Application Insights. Il minidump, dopo essere stato correttamente caricato, viene eliminato dal disco. I file di log dell'utilità di caricamento del minidump vengono conservati sul disco. In un ambiente del servizio app questi log si trovano in D:\Home\LogFiles\Uploader_*.log. Usare il sito di gestione di Kudu per il servizio app per trovare questi file di log.

  1. Aprire l'applicazione del servizio app nel portale di Azure.

  2. Selezionare il pannello Strumenti avanzati o cercare Kudu.

  3. Fare clic su Vai.
  4. Nell'elenco a discesa Console di debug selezionare CMD.
  5. Fare clic su LogFiles.

Verrà visualizzato almeno un file con il nome che inizia con Uploader_ e l'estensione .log. Fare clic sull'icona appropriata per scaricare i file di log o aprirli in un browser. Il nome file include il nome del computer. Se l'istanza del servizio app è ospitata in più di un computer, è presente un file di log separato per ogni computer. Quando l'utilità di caricamento rileva un nuovo file di minidump file, il file viene registrato nel file di log. Ecco un esempio di caricamento corretto:

MinidumpUploader.exe Information: 0 : Dump available 139e411a23934dc0b9ea08a626db16c5.dmp
    DateTime=2017-05-25T14:25:08.0349846Z
MinidumpUploader.exe Information: 0 : Uploading D:\local\Temp\Dumps\c12a605e73c44346a984e00000000000\139e411a23934dc0b9ea08a626db16c5.dmp, 329.12 MB
    DateTime=2017-05-25T14:25:16.0145444Z
MinidumpUploader.exe Information: 0 : Upload successful.
    DateTime=2017-05-25T14:25:42.9164120Z
MinidumpUploader.exe Information: 0 : Extracting PDB info from D:\local\Temp\Dumps\c12a605e73c44346a984e00000000000\139e411a23934dc0b9ea08a626db16c5.dmp.
    DateTime=2017-05-25T14:25:42.9164120Z
MinidumpUploader.exe Information: 0 : Matched 2 PDB(s) with local files.
    DateTime=2017-05-25T14:25:44.2310982Z
MinidumpUploader.exe Information: 0 : Stamp does not want any of our matched PDBs.
    DateTime=2017-05-25T14:25:44.5435948Z
MinidumpUploader.exe Information: 0 : Deleted D:\local\Temp\Dumps\c12a605e73c44346a984e00000000000\139e411a23934dc0b9ea08a626db16c5.dmp
    DateTime=2017-05-25T14:25:44.6095821Z

Nell'esempio precedente la chiave di strumentazione è c12a605e73c44346a984e00000000000. Questo valore deve corrispondere alla chiave di strumentazione dell'applicazione. Il minidump è associato a uno snapshot con l'ID 139e411a23934dc0b9ea08a626db16c5. Sarà possibile usare questo ID in seguito per individuare i dati di telemetria delle eccezioni associati in Application Insights Analytics.

L'utilità di caricamento cerca i nuovi file PDB ogni 15 minuti circa. Ad esempio:

MinidumpUploader.exe Information: 0 : PDB rescan requested.
    DateTime=2017-05-25T15:11:38.8003886Z
MinidumpUploader.exe Information: 0 : Scanning D:\home\site\wwwroot\ for local PDBs.
    DateTime=2017-05-25T15:11:38.8003886Z
MinidumpUploader.exe Information: 0 : Scanning D:\local\Temporary ASP.NET Files\root\a6554c94\e3ad6f22\assembly\dl3\81d5008b\00b93cc8_dec5d201 for local PDBs.
    DateTime=2017-05-25T15:11:38.8160276Z
MinidumpUploader.exe Information: 0 : Local PDB scan complete. Found 2 PDB(s).
    DateTime=2017-05-25T15:11:38.8316450Z
MinidumpUploader.exe Information: 0 : Deleted PDB scan marker D:\local\Temp\Dumps\c12a605e73c44346a984e00000000000\.pdbscan.
    DateTime=2017-05-25T15:11:38.8316450Z

Per le applicazioni non ospitate nel servizio app, i log di caricamento sono nella stessa cartella dei minidump: %TEMP%\Dumps\<ikey> (dove <ikey> è la chiave di strumentazione).

Usare la ricerca di Application Insights per trovare le eccezioni con gli snapshot

Quando viene creato uno snapshot, l'eccezione generata viene contrassegnata con un ID snapshot. Quando i dati di telemetria dell'eccezione vengono segnalati ad Application Insights, tale ID snapshot viene incluso come proprietà personalizzata. Usando il pannello Ricerca in Application Insights, è possibile trovare tutti i dati di telemetria con la proprietà personalizzata ai.snapshot.id.

  1. Passare alla risorsa di Application Insights nel portale di Azure.
  2. Fare clic su Search(Cerca).
  3. Digitare ai.snapshot.id nella casella di testo di ricerca e premere INVIO.

Cercare i dati di telemetria con i ID snapshot nel portale

Se questa ricerca non restituisce risultati, significa che nessuno snapshot è stato segnalato ad Application Insights per l'applicazione nell'intervallo di tempo selezionato.

Per cercare uno specifico ID snapshot dei log di caricamento, digitare tale ID nella casella di ricerca. Se non è possibile trovare dati di telemetria per uno snapshot che è stato sicuramente caricato, seguire questa procedura:

  1. Controllare di esaminare la risorsa di Application Insights corretta verificando la chiave di strumentazione.

  2. Usando il timestamp del log di caricamento, modificare il filtro Intervallo di tempo della ricerca per coprire tale intervallo di tempo.

Se ancora non vengono visualizzate eccezioni con tale ID snapshot, significa che i dati di telemetria dell'eccezione non sono stati segnalati ad Application Insights. Questa situazione si può verificare se l'applicazione ha subito un arresto anomalo del sistema dopo avere acquisito lo snapshot, ma prima di segnalare i dati di telemetria dell'eccezione. In questo caso, controllare i log del servizio app in Diagnose and solve problems per accertare se si sono verificati riavvi non previsti o eccezioni non gestite.

Passaggi successivi