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 strumenti di diagnostica e può essere usato per elaborare eventi generati dal runtime, e anche per 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 NetTrace, vedere la documentazione sul formato NetTrace.

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. Senza altri strumenti di tracciamento, gli eventi EventPipe includono solo tracce dello stack con informazioni sui frame di codice gestito. Per ottenere eventi da altre librerie in modalità utente non gestite, campionamento della CPU per codice nativo o eventi del kernel, usare strumenti di traccia specifici del sistema operativo, ad esempio ETW o perf_events. In Linux lo strumento perfcollect consente di automatizzare l'uso di perf_events e LTTng.

A partire da .NET 10, EventPipe in Linux può generare eventi come user_events, abilitare la raccolta di eventi gestiti, eventi del sistema operativo/kernel e stack di chiamate nativi in una singola traccia unificata. Questa modalità richiede privilegi di amministratore/root e il kernel Linux 6.4+. Per altre informazioni, vedere dotnet-trace collect-linux.

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. Usando lo standard EventPipe, è possibile tracciare le applicazioni a condizione che il tracer (ad esempio, dotnet-trace) venga eseguito dallo stesso utente che ha avviato l'applicazione. La modalità EventPipe (user_events) descritta in precedenza richiede privilegi di amministratore/radice perché interagisce con l'infrastruttura di traccia a livello di sistema operativo.

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 i dump dell'heap GC dei processi attivi per analizzare l'heap gestito di un'applicazione.

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

Tracciare usando le 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 interrompere la registrazione, esci dall'applicazione.

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

• DOTNET_EventPipeOutputPath: il percorso del file di traccia di output di EventPipe quando è configurato per l'esecuzione attraverso 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ò saturare questo buffer e alcuni eventi possono 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 saperne di più su alcuni dei provider più noti in .NET, vedere Provider di eventi noti.