Introduzione a EventSource
Questo articolo si applica a: ✔️ .NET Core 3.1 e versioni successive ✔️ .NET Framework 4.5 e versioni successive
Questa procedura dettagliata illustra come registrare un nuovo evento con System.Diagnostics.Tracing.EventSource, raccogliere eventi in un file di traccia, visualizzare la traccia e comprendere i concetti di base di EventSource.
Nota
Molte tecnologie integrate con EventSource usano i termini “Tracciamento” e “Tracce” anziché “Registrazione” e “Registri”. Il significato qui è lo stesso.
Registrare un evento
L'obiettivo di EventSource è consentire agli sviluppatori .NET di scrivere codice simile al seguente per registrare un evento:
DemoEventSource.Log.AppStarted("Hello World!", 12);
Questa riga di codice include un oggetto di registrazione (DemoEventSource.Log), un metodo che rappresenta l'evento da registrare (AppStarted) e, facoltativamente, alcuni parametri di evento fortemente tipizzato (HelloWorld! e 12). Non sono presenti livelli di dettaglio, ID evento, modelli di messaggio o qualsiasi altro elemento che non deve trovarsi nel sito di chiamata. Tutte queste altre informazioni sugli eventi vengono scritte definendo una nuova classe derivata da System.Diagnostics.Tracing.EventSource.
Ecco un esempio minimo completo:
using System.Diagnostics.Tracing;
namespace EventSourceDemo
{
public static class Program
{
public static void Main(string[] args)
{
DemoEventSource.Log.AppStarted("Hello World!", 12);
}
}
[EventSource(Name = "Demo")]
class DemoEventSource : EventSource
{
public static DemoEventSource Log { get; } = new DemoEventSource();
[Event(1)]
public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
}
}
La classe DemoEventSource dichiara un metodo per ogni tipo di evento che si desidera registrare. In questo caso, un singolo evento denominato "AppStarted" viene definito dal metodo AppStarted(). Ogni volta che il codice richiama il metodo AppStarted, viene registrato un altro evento AppStarted nella traccia, se l'evento è abilitato. Ecco alcuni dei dati che possono essere acquisiti con ogni evento:
- Nome evento: nome che identifica il tipo di evento registrato. Il nome dell'evento sarà identico al nome del metodo, “AppStarted” in questo caso.
- ID evento: ID numerico che identifica il tipo di evento registrato. Ha un ruolo simile al nome, ma può essere utile per l'elaborazione automatica rapida dei log. L'evento AppStarted ha un ID 1, specificato in EventAttribute.
- Nome origine: nome dell'EventSource che contiene l'evento. Viene usato come spazio dei nomi per gli eventi. I nomi e gli ID evento devono essere univoci solo nell'ambito dell'origine. Qui l'origine è denominata "Demo", specificata in EventSourceAttribute, nella definizione della classe. Il nome di origine viene comunemente definito anche nome del provider.
- Argomenti: tutti i valori degli argomenti del metodo vengono serializzati.
- Altre informazioni: gli eventi possono anche contenere timestamp, ID thread, ID processore, ID attività, analisi dello stack e metadati degli eventi, ad esempio modelli di messaggio, livelli di dettaglio e parole chiave.
Per altre informazioni e procedure consigliate per la creazione di eventi, vedi Strumentazione del codice per la creazione di eventi.
Raccogliere e visualizzare un file di traccia
Non è necessaria alcuna configurazione nel codice che descrive gli eventi da abilitare, dove devono essere inviati i dati registrati o il formato in cui archiviare i dati. Se esegui l'app ora, per impostazione predefinita non produrrà alcun file di traccia. EventSource usa il criterio Publish-subscribe, che richiede ai sottoscrittori di indicare gli eventi che devono essere abilitati e di controllare tutta la serializzazione per gli eventi sottoscritti. EventSource include integrazioni per la sottoscrizione da Event Tracing for Windows (ETW) e EventPipe (solo .NET Core). È possibile creare sottoscrittori personalizzati anche usando l'API System.Diagnostics.Tracing.EventListener.
Questa demo mostra un esempio di EventPipe per le app .NET Core. Per conoscere altre opzioni, vedi Raccolta e visualizzazione delle tracce degli eventi. EventPipe è una tecnologia di tracciamento aperta e multipiattaforma integrata nel runtime di .NET Core, che offre agli sviluppatori .NET strumenti di raccolta di tracce e un formato di traccia compatta portatile (file *.nettrace). dotnet-trace è uno strumento da riga di comando che raccoglie le tracce EventPipe.
- Scarica e installa dotnet-trace
- Compila l'app console precedente. Questa demo presuppone che l'app sia denominata EventSourceDemo.exe e che si trovi nella directory corrente. All'esecuzione della riga di comando:
>dotnet-trace collect --providers Demo -- EventSourceDemo.exe
L'output dovrebbe essere simile al seguente:
Provider Name Keywords Level Enabled By
Demo 0xFFFFFFFFFFFFFFFF Verbose(5) --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_20220303_001619.nettrace
[00:00:00:00] Recording trace 0.00 (B)
Press <Enter> or <Ctrl+C> to exit...
Trace completed.
Questo comando ha eseguito EventSourceDemo.exe con tutti gli eventi nell’EventSource “Demo” abilitati e ha restituito il file di traccia EventSourceDemo.exe_20220303_001619.nettrace.
L'apertura del file in Visual Studio mostra gli eventi registrati.
Nella visualizzazione elenco, puoi vedere che il primo evento è Demo/AppStarted. La colonna di testo contiene gli argomenti salvati, la colonna timestamp indica che l'evento si è verificato 27 ms dopo l'avvio della registrazione e a destra è possibile visualizzare il callstack. Gli altri eventi vengono abilitati automaticamente in ogni traccia raccolta da dotnet-trace, anche se possono essere ignorati e filtrati nella visualizzazione dell'interfaccia utente, se non servono. Questi eventi aggiuntivi acquisiscono alcune informazioni sul processo e sul codice jitted, il che consente a Visual Studio di ricostruire l’analisi dello stack di eventi.
