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.

Nota

Verificare che l'applicazione faccia riferimento alla versione 2.1.1 o più recente del pacchetto Microsoft.ApplicationInsights.AspNetCore.

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

  2. Modificare il metodo ConfigureServices nella classe Startup dell'applicazione per aggiungere il processore di telemetria dell'agente di raccolta snapshot.

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

Concedere le autorizzazioni

Gli snapshot possono essere ispezionati dai proprietari della sottoscrizione di Azure. Agli altri utenti deve essere concessa l'autorizzazione da un proprietario.

Per concedere l'autorizzazione, assegnare il ruolo Application Insights Snapshot Debugger agli utenti che ispezioneranno gli snapshot. Questo ruolo può essere assegnato a singoli utenti o gruppi dai proprietari della sottoscrizione per la risorsa di Application Insights di destinazione oppure per il gruppo di risorse o la sottoscrizione di tale risorsa.

  1. Aprire il pannello Controllo di accesso (IAM).
  2. Fare clic sul pulsante +Aggiungi.
  3. Selezionare Debugger di snapshot di Application Insights nell'elenco a discesa Ruoli.
  4. Cercare e immettere un nome per l'utente da aggiungere.
  5. Fare clic sul pulsante Salva per aggiungere l'utente al ruolo.

[!IMPORTANT] Gli snapshot possono contenere informazioni personali e altre informazioni riservate nei valori delle variabili e dei parametri.

Snapshot di debug nel portale di Application Insights

Se è disponibile uno snapshot per una determinata eccezione o un determinato ID problema, viene visualizzato il pulsante Open Debug Snapshot (Apri snapshot di debug) per l'eccezione nel portale di Application Insights.

Pulsante Open Debug Snapshot per l'eccezione

Nella vista Debug Snapshot (Snapshot di debug) vengono visualizzati uno stack di chiamate e un riquadro delle variabili. Quando si selezionano frame dello stack di chiamate nel riquadro corrispondente, è possibile visualizzare i parametri e le variabili locali per la chiamata di funzione nel riquadro delle variabili.

Visualizzare uno snapshot di debug nel portale

Gli snapshot potrebbero contenere informazioni riservate e per impostazione predefinita non sono visibili. Per visualizzare gli snapshot, è necessario che all'utente sia stato assegnato il ruolo Application Insights Snapshot Debugger.

Snapshot di debug con Visual Studio 2017 Enterprise

  1. Fare clic sul pulsante Download Snapshot (Scarica snapshot) per scaricare un file .diagsession che può essere aperto con Visual Studio 2017 Enterprise.

  2. Per aprire il file .diagsession, è necessario prima di tutto scaricare e installare l'estensione Snapshot Debugger per Visual Studio.

  3. Quando si apre il file di snapshot, in Visual Studio viene visualizzata la pagina per il debug di minidump. Fare clic su Debug Managed Code (Debug codice gestito) per avviare il debug dello snapshot. Lo snapshot viene aperto alla riga di codice in cui è stata generata l'eccezione in modo da consentire il debug dello stato corrente del processo.

    Visualizzare lo snapshot di debug in Visual Studio

Lo snapshot scaricato contiene tutti file di simboli trovati nel server applicazioni Web. Questi file di simboli sono necessari per associare i dati degli snapshot al codice sorgente. Per le app del servizio app, assicurarsi di abilitare la distribuzione dei simboli al momento della pubblicazione delle app Web.

Funzionamento degli snapshot

All'avvio dell'applicazione viene creato un processo di caricamento degli snapshot separato che monitora le richieste di snapshot nell'applicazione. Quando viene richiesto uno snapshot, viene creata una copia shadow del processo in esecuzione in circa 10-20 millisecondi. Il processo shadow viene quindi analizzato e viene creato uno snapshot mentre il processo principale rimane in esecuzione e continua a gestire il traffico verso gli utenti. Lo snapshot viene quindi caricato in Application Insights insieme agli eventuali file di simboli pertinenti (con estensione pdb) che sono necessari per visualizzare lo snapshot.

Limitazioni correnti

Pubblicare i simboli

Per poter decodificare le variabili e offrire un'esperienza di debug in Visual Studio, Snapshot Debugger richiede la presenza dei file di simboli nel server di produzione. Per impostazione predefinita, la versione 15.2 di Visual Studio 2017 pubblica i simboli per le build di versione durante la pubblicazione nel servizio app. Nelle versioni precedenti è necessario aggiungere la riga seguente al file .pubxml del profilo di pubblicazione per pubblicare i simboli in modalità versione:

    <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