Raccogliere e visualizzare tracce EventSource

Questo articolo si applica a: ✔️ .NET Core 3.1 e versioni successive ✔️ .NET Framework 4.5 e versioni successive

La guida introduttiva ha illustrato come creare un oggetto EventSource minimo e raccogliere eventi in un file di traccia. Questa esercitazione illustra in che modo diversi strumenti possono configurare gli eventi raccolti in una traccia e quindi visualizzare le tracce.

App di esempio

Si userà l'app di esempio seguente che genera eventi per questa esercitazione. Compilare un'applicazione console .NET contenente il codice seguente:

using System.Diagnostics.Tracing;

namespace EventSourceDemo
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            DemoEventSource.Log.AppStarted("Hello World!", 12);
            DemoEventSource.Log.DebugMessage("Got here");
            DemoEventSource.Log.DebugMessage("finishing startup");
            DemoEventSource.Log.RequestStart(3);
            DemoEventSource.Log.RequestStop(3);
        }
    }

    [EventSource(Name = "Demo")]
    class DemoEventSource : EventSource
    {
        public static DemoEventSource Log { get; } = new DemoEventSource();

        [Event(1, Keywords = Keywords.Startup)]
        public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
        [Event(2, Keywords = Keywords.Requests)]
        public void RequestStart(int requestId) => WriteEvent(2, requestId);
        [Event(3, Keywords = Keywords.Requests)]
        public void RequestStop(int requestId) => WriteEvent(3, requestId);
        [Event(4, Keywords = Keywords.Startup, Level = EventLevel.Verbose)]
        public void DebugMessage(string message) => WriteEvent(4, message);


        public class Keywords
        {
            public const EventKeywords Startup = (EventKeywords)0x0001;
            public const EventKeywords Requests = (EventKeywords)0x0002;
        }
    }
}

Configurare gli eventi da raccogliere

La maggior parte degli strumenti di raccolta eventi usa queste opzioni di configurazione per decidere quali eventi devono essere inclusi in una traccia:

• Nomi provider: elenco di uno o più nomi EventSource. Solo gli eventi definiti in EventSources in questo elenco sono idonei per essere inclusi. Per raccogliere eventi dalla classe DemoEventSource nell'app di esempio precedente, è necessario includere il nome EventSource "Demo" nell'elenco dei nomi dei provider.
• Livello di dettaglio dell'evento: per ogni provider è possibile definire un livello di dettaglio ed eventi con livello di dettaglio superiore a quello che verrà escluso dalla traccia. Se è stato specificato che il provider "Demo" nell'app di esempio precedente deve raccogliere a livello di dettaglio informativo, l'evento DebugMessage verrebbe escluso perché ha un livello superiore. Se si specifica EventLevel LogAlways(0) è un caso speciale che indica che devono essere inclusi eventi di qualsiasi livello di dettaglio.
• Parole chiave evento: per ogni provider è possibile definire un set di parole chiave e verranno inclusi solo gli eventi contrassegnati con almeno una delle parole chiave. Nell'app di esempio precedente se è stata specificata la parola chiave Startup, verranno inclusi solo gli eventi AppStarted e DebugMessage. Se non vengono specificate parole chiave, si tratta di un caso speciale e significa che gli eventi con qualsiasi parola chiave devono essere inclusi.

Convenzioni per la descrizione della configurazione del provider

Anche se ogni strumento determina la propria interfaccia utente per l'impostazione della configurazione della traccia, è presente una convenzione comune che molti strumenti usano quando si specifica la configurazione come stringa di testo. L'elenco dei provider viene specificato come elenco delimitato da punti e virgola e ogni elemento del provider nell'elenco è costituito da nome, parole chiave e livello separati da due punti. Ad esempio, "Demo:3:5" identifica EventSource denominato "Demo" con la parola chiave maschera di bit 3 (bit Startup e bit Requests) e EventLevel 5, ovvero Verbose. Molti strumenti consentono anche di omettere il livello e le parole chiave se non si vuole filtrare alcun livello o parola chiave. Ad esempio, "Demo::5" esegue solo filtri basati sul livello, "Demo:3" esegue solo il filtro basato su parole chiave e "Demo" non esegue filtri di parole chiave o a livello.

Visual Studio

Il profiler di Visual Studio supporta sia la raccolta che la visualizzazione di tracce. Può anche visualizzare tracce raccolte in anticipo da altri strumenti, ad esempio dotnet-trace.

Raccogliere una traccia

La maggior parte degli strumenti di profilatura di Visual Studio usa set predefiniti di eventi che servono a uno scopo specifico, ad esempio l'analisi dell'utilizzo o delle allocazioni della CPU. Per raccogliere una traccia con eventi personalizzati, si userà lo strumento Visualizzatore eventi.

1. Per aprire Il Profiler prestazioni in Visual Studio, selezionare ALT+F2.

2. Selezionare la casella di controllo Visualizzatore eventi.

   

3. Selezionare l'icona a forma di ingranaggio a destra di Visualizzatore eventi per aprire la finestra di configurazione.

   Nella seguente tabella Provider aggiuntivi aggiungere una riga per ogni provider da configurare facendo clic sulla casella di controllo Abilitato e quindi immettendo il nome del provider, le parole chiave e il livello. Non è necessario immettere il GUID del provider; viene calcolato automaticamente.

   

4. Selezionare OK per confermare le impostazioni di configurazione.

5. Selezionare Avvio per iniziare a eseguire l'app e raccogliere i log.

6. Selezionare Arresta raccolta o uscire dall'app per interrompere la raccolta dei log e visualizzare i dati raccolti.

Visualizzare una traccia

Visual Studio può visualizzare le tracce raccolte o visualizzare le tracce raccolte in altri strumenti. Per visualizzare le tracce da altri strumenti, usare File>Apri e selezionare un file di traccia nella selezione file. Il profiler di Visual Studio supporta file .etl (formato standard ETW), file .nettrace (formato standard di EventPipe) e file .diagsession (formato standard di Visual Studio). Per informazioni sull'uso dei file di traccia in Visual Studio, consultare la documentazione di Visual Studio.

Nota

Visual Studio raccoglie automaticamente alcuni eventi da ETW o EventPipe, anche se non sono stati configurati in modo esplicito. Se vengono visualizzati eventi non riconosciuti nella colonna Nome provider o Nome evento e si vuole filtrarli, usare l'icona del filtro a destra per selezionare solo gli eventi da visualizzare.

PerfView

PerfView è uno strumento per le prestazioni creato dal team .NET che può raccogliere e visualizzare tracce ETW. Può anche visualizzare i file di traccia raccolti da altri strumenti in vari formati. In questa esercitazione si raccoglierà una traccia ETW dell'app demo e quindi si esamineranno gli eventi raccolti nel visualizzatore eventi di PerfView.

Raccogliere una traccia

1. Scaricare PerfView dalla pagina delle versioni. Questa esercitazione è stata eseguita con PerfView versione 2.0.76, ma qualsiasi versione recente dovrebbe funzionare.

2. Avviare PerfView.exe con autorizzazioni di amministratore.

   Nota

   La raccolta di traccia ETW richiede sempre autorizzazioni di amministratore, tuttavia se si usa solo PerfView per visualizzare una traccia preesistente, non sono necessarie autorizzazioni speciali.

   

3. Dal menu Raccogli selezionare Esegui. Verrà aperta una nuova finestra di dialogo in cui si immetterà il percorso dell'app demo.

   

4. Per configurare gli eventi raccolti, espandere Opzioni avanzate nella parte inferiore della finestra di dialogo. Nella casella di testo Provider aggiuntivi immettere provider usando il formato di testo convenzionale descritto in precedenza. In questo caso, si immette "Demo:1:4", ovvero parola chiave bit 1 (Startup eventi) e dettaglio 4 (Informational).

   

5. Per avviare l'app e iniziare a raccogliere la traccia, selezionare il pulsante Esegui comando. Quando l'app viene chiusa, la traccia PerfViewData.etl viene salvata nella directory attuale.

Visualizzare una traccia

1. Nella casella di testo a discesa della finestra principale in alto a sinistra selezionare la directory contenente il file di traccia. Fare quindi doppio clic sul file di traccia nella visualizzazione struttura ad albero seguente.

   

2. Per visualizzare il Visualizzatore eventi, fare doppio clic sull'elemento Eventi visualizzato nella visualizzazione struttura ad albero sotto il file di traccia.

   

3. Tutti i tipi di evento nella traccia vengono visualizzati nell'elenco a sinistra. Fare doppio clic su un tipo di evento, ad esempio Demo\AppStarted, per visualizzare tutti gli eventi di quel tipo nella tabella a destra.

   

Altre informazioni

Per ulteriori informazioni sull'uso di PerfView, consultare le esercitazioni video PerfView.

dotnet-trace

dotnet-trace è uno strumento da riga di comando multipiattaforma in grado di raccogliere tracce dalle app .NET Core usando la traccia EventPipe. Non supporta la visualizzazione dei dati di traccia, ma le tracce raccolte possono essere visualizzate da altri strumenti, ad esempio PerfView o Visual Studio. dotnet-trace supporta anche la conversione delle tracce di formato predefinite .nettrace in altri formati, ad esempio Chromium o Speedscope.

Raccogliere una traccia

1. Scaricare e installare dotnet-trace.

2. Nella riga di comando eseguire il comando dotnet-trace collect:

   E:\temp\EventSourceDemo\bin\Debug\net6.0>dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe
   

   L'output dovrebbe essere simile al seguente:

   E:\temp\EventSourceDemo\bin\Debug\net6.0> dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe
   
   Provider Name                           Keywords            Level               Enabled By
   Demo                                    0x0000000000000001  Informational(4)    --providers
   
   Launching: EventSourceDemo.exe
   Process        : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe
   Output File    : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe_20220317_021512.nettrace
   
   [00:00:00:00]   Recording trace 0.00     (B)
   Press <Enter> or <Ctrl+C> to exit...
   
   Trace completed.
   

   dotnet-trace usa il formato di testo convenzionale per descrivere la configurazione del provider nell'argomento --providers. Per altre opzioni su come acquisire tracce usando dotnet-trace, consultare la documentazione dotnet-trace.

EventListener

System.Diagnostics.Tracing.EventListener è un'API .NET che può essere usata da in-process per ricevere callback per gli eventi generati da un oggetto System.Diagnostics.Tracing.EventSource. Questa API può essere usata per creare strumenti di registrazione personalizzati o per analizzare gli eventi in memoria senza mai serializzarli.

Per usare EventListener, dichiarare un tipo che deriva da EventListener, richiamare EnableEvents per sottoscrivere gli eventi da qualsiasi EventSource di interesse ed eseguire l'override di OnEventWritten, che verrà chiamato ogni volta che è disponibile un nuovo evento. Spesso è utile eseguire l'override OnEventSourceCreated per individuare gli oggetti EventSource esistenti, ma questo non è obbligatorio. Di seguito è riportata un'implementazione di esempio EventListener che viene stampata nella console quando vengono ricevuti messaggi:

1. Aggiungere questo codice all'app demo.

   class ConsoleWriterEventListener : EventListener
   {
       protected override void OnEventSourceCreated(EventSource eventSource)
       {
           if(eventSource.Name == "Demo")
           {
               EnableEvents(eventSource, EventLevel.Informational);
           }
       }
   
       protected override void OnEventWritten(EventWrittenEventArgs eventData)
       {
           Console.WriteLine(eventData.TimeStamp + " " + eventData.EventName);
       }
   }
   

2. Modificare il metodo Main per creare un'istanza del nuovo listener.

   public static void Main(string[] args)
   {
       ConsoleWriterEventListener listener = new ConsoleWriterEventListener();
   
       DemoEventSource.Log.AppStarted("Hello World!", 12);
       DemoEventSource.Log.DebugMessage("Got here");
       DemoEventSource.Log.DebugMessage("finishing startup");
       DemoEventSource.Log.RequestStart(3);
       DemoEventSource.Log.RequestStop(3);
   }
   

3. Compilare ed eseguire l'app. In precedenza, non aveva output, ma ora scrive gli eventi nella console:

   3/24/2022 9:23:35 AM AppStarted
   3/24/2022 9:23:35 AM RequestStart
   3/24/2022 9:23:35 AM RequestStop