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 che si integrano con EventSource usano i termini 'Tracing' e 'Traces' anziché 'Logging' e 'Logs'. Il significato è lo stesso qui.
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. Questo è un ruolo simile al nome, ma può essere utile per l'elaborazione automatica rapida dei log. L'evento AppStarted ha un ID 1, specificato nel EventAttribute.
- Nome origine: nome dell'oggetto EventSource che contiene l'evento. Viene usato come spazio dei nomi per gli eventi. I nomi e gli ID degli eventi devono essere univoci solo nell'ambito dell'origine. Qui l'origine è denominata "Demo", specificata nella 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, vedere Codice di strumentazione per creare 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, non produrrà alcun file di traccia per impostazione predefinita. EventSource usa il modello 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 ha integrazioni per la sottoscrizione da Event Tracing for Windows (ETW) e EventPipe (solo .NET Core). È anche possibile creare sottoscrittori personalizzati usando l'API System.Diagnostics.Tracing.EventListener.
Questa demo mostra un EventPipe esempio per le app .NET Core. Per altre informazioni sulle opzioni, vedere Raccolta e visualizzazione di tracce di eventi. EventPipe è una tecnologia di traccia aperta e multipiattaforma integrata nel runtime di .NET Core per offrire agli sviluppatori .NET strumenti di raccolta di tracce e un formato di traccia compatto portabile (file *.nettrace). dotnet-trace è uno strumento da riga di comando che raccoglie le tracce EventPipe.
- Scaricare e installare dotnet-trace.
- Costruisci l'app console sopra. Questa demo presuppone che l'app sia denominata EventSourceDemo.exe e che si trova 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 in 'Demo' EventSource abilitati e ha prodotto 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 è l'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 lo stack di chiamate. Gli altri eventi vengono abilitati automaticamente in ogni traccia raccolta da dotnet-trace, anche se possono essere ignorati e filtrati dalla visualizzazione nell'interfaccia utente se sono distratti. Questi eventi aggiuntivi acquisiscono alcune informazioni sul processo e sul codice jitted, che consente a Visual Studio di ricostruire le tracce dello stack di eventi.
