EventPipe

EventPipe è un componente di runtime che può essere utilizzato per raccogliere dati di traccia, in modo simile a ETW o a perf_events. L'obiettivo di EventPipe è consentire agli sviluppatori .NET di tracciare facilmente le applicazioni .NET senza dover fare affidamento su componenti con privilegi elevati specifici della piattaforma, come ETW o perf_events.

EventPipe è il meccanismo dietro molti degli strumenti di diagnostica e può essere usato per l'utilizzo di eventi generati dal runtime, nonché eventi personalizzati scritti con EventSource.

Questo articolo è una panoramica generale di EventPipe. Descrive quando e come usare EventPipe e come configurarlo in base alle proprie esigenze.

Nozioni di base su EventPipe

EventPipe aggrega gli eventi generati dai componenti di runtime, ad esempio il compilatore Just-In-Time o il Garbage Collector, e gli eventi scritti dalle istanze di EventSource nelle librerie e nel codice utente.

Gli eventi vengono quindi serializzati nel formato di file .nettrace e possono essere scritti direttamente in un file o trasmessi tramite una porta di diagnostica per l'utilizzo out-of-process.

Per altre informazioni sul formato di serializzazione EventPipe, vedere la documentazione sul formato EventPipe.

Differenze tra EventPipe e ETW/perf_events

EventPipe fa parte del runtime .NET ed è progettato per funzionare allo stesso modo in tutte le piattaforme supportate da .NET Core. Ciò consente agli strumenti di traccia basati su EventPipe, ad esempio dotnet-counters, dotnet-gcdump e dotnet-trace, di funzionare senza problemi tra le piattaforme.

Tuttavia, poiché EventPipe è un componente predefinito del runtime, il suo ambito è limitato al codice gestito e al runtime stesso. Gli eventi EventPipe includono tracce dello stack con informazioni solo sui frame di codice gestito. Se si desidera che gli eventi generati da altre librerie in modalità utente non gestite, il campionamento della CPU per il codice nativo o gli eventi del kernel, è consigliabile usare strumenti di traccia specifici del sistema operativo, come ETW o perf_events. Su Linux lo strumento perfcollect aiuta ad automatizzare l'uso di perf_events e di LTTng.

Un'altra differenza importante tra EventPipe e ETW/perf_events è il requisito dei privilegi admin/root. Per tracciare un'applicazione utilizzando ETW o perf_events è necessario essere un amministratore/root. Se si usa EventPipe, è possibile tracciare le applicazioni purché l'analisi (ad esempio, dotnet-trace) venga eseguita come lo stesso utente che ha avviato l'applicazione.

Nella tabella seguente è riportato un riepilogo delle differenze tra EventPipe e ETW/perf_events.

Usare EventPipe per tenere traccia dell'applicazione .NET

È possibile usare EventPipe per tenere traccia dell'applicazione .NET in molti modi:

• Usare uno degli strumenti di diagnostica basati su EventPipe.

• Usare la libreria Microsoft.Diagnostics.NETCore.Client per scrivere uno strumento personalizzato per configurare e avviare sessioni di EventPipe.

• Usare le variabili di ambiente per avviare EventPipe.

Dopo aver prodotto un file nettrace contenente gli eventi EventPipe, è possibile visualizzare il file in PerfView o Visual Studio. Nelle piattaforme diverse da Windows è possibile convertire il file nettrace in un formato di traccia speedscope o Chromium usando il comando dotnet-trace convert e visualizzarlo con Speedscope o Chrome DevTools.

È anche possibile analizzare le tracce EventPipe a livello di programmatico con TraceEvent.

Strumenti che usano EventPipe

Questo è il modo più semplice per usare EventPipe per tracciare l'applicazione. Per altre informazioni su come usare ognuno di questi strumenti, vedere la documentazione di ogni strumento.

• dotnet-counters consente di monitorare e raccogliere varie metriche generate dal runtime e dalle librerie principali di .NET, nonché metriche personalizzate che è possibile scrivere.

• dotnet-gcdump consente di raccogliere dump di arresto anomalo dell'heap GC dei processi in tempo reale per l'analisi dell'heap gestito di un'applicazione.

• dotnet-trace consente di raccogliere tracce di applicazioni da analizzare per ottenere prestazioni.

Traccia delle variabili di ambiente

Il meccanismo preferito per l'uso di EventPipe consiste nell'usare dotnet-trace o la libreria Microsoft.Diagnostics.NETCore.Client.

È tuttavia possibile usare le variabili di ambiente seguenti per configurare una sessione di EventPipe in un'app e scrivere la traccia direttamente in un file. Per arrestare la traccia, uscire dall'applicazione.

• DOTNET_EnableEventPipe: impostare su 1 per avviare una sessione EventPipe che scrive direttamente in un file. Il valore predefinito è 0.

• DOTNET_EventPipeOutputPath: il percorso del file di traccia EventPipe di output quando è configurato per l'esecuzione tramite DOTNET_EnableEventPipe. Il valore predefinito è trace.nettrace, che verrà creato nella stessa directory da cui è in esecuzione l'app.

  Nota

  A partire da .NET 6, le istanze della stringa {pid} in DOTNET_EventPipeOutputPath vengono sostituite con l'ID processo del processo di cui tenere traccia.

• DOTNET_EventPipeCircularMB: il valore esadecimale che rappresenta le dimensioni del buffer interno di EventPipe in megabyte. Questo valore di configurazione viene usato solo quando EventPipe è configurato per l'esecuzione tramite DOTNET_EnableEventPipe. La dimensione predefinita del buffer è 1024 MB, che si traduce in questa variabile di ambiente impostata su 400, poiché 0x400 == 1024.

  Nota

  Se il processo di destinazione scrive gli eventi troppo frequentemente, può eseguire l'overflow di questo buffer e alcuni eventi potrebbero essere eliminati. Se vengono eliminati troppi eventi, è possibile aumentare le dimensioni del buffer per verificare se il numero di eventi eliminati si riduce. Se il numero di eventi eliminati non diminuisce con una dimensione del buffer maggiore, può essere dovuto a un lettore lento che impedisce lo scaricamento dei buffer del processo di destinazione.

• DOTNET_EventPipeProcNumbers: impostare questa opzione su 1 per abilitare l'acquisizione dei numeri del processore nelle intestazioni di evento EventPipe. Il valore predefinito è 0.

• DOTNET_EventPipeConfig: configurare la configurazione della sessione EventPipe all'avvio di una sessione EventPipe con DOTNET_EnableEventPipe. La sintassi è la seguente:

  <provider>:<keyword>:<level>

  È anche possibile specificare più provider concatenandoli con una virgola:

  <provider1>:<keyword1>:<level1>,<provider2>:<keyword2>:<level2>

  Se questa variabile di ambiente non è impostata ma EventPipe è abilitata da DOTNET_EnableEventPipe, inizierà la traccia abilitando i provider seguenti con le parole chiave e i livelli seguenti:

  • Microsoft-Windows-DotNETRuntime:4c14fccbd:5
  • Microsoft-Windows-DotNETRuntimePrivate:4002000b:5
  • Microsoft-DotNETCore-SampleProfiler:0:5

  Per altre informazioni su alcuni dei provider noti in .NET, vedere Provider di eventi noti.