Dela via

EventPipe

  • Artikel

EventPipe är en körningskomponent som kan användas för att samla in spårningsdata, som liknar ETW eller perf_events. Målet med EventPipe är att .NET-utvecklare enkelt ska kunna spåra sina .NET-program utan att behöva förlita sig på plattformsspecifika komponenter med hög behörighet, till exempel ETW eller perf_events.

EventPipe är mekanismen bakom många av diagnostikverktygen och kan användas för att använda händelser som genereras av körningen samt anpassade händelser som skrivits med EventSource.

Den här artikeln är en översikt över EventPipe på hög nivå. Den beskriver när och hur du använder EventPipe och hur du konfigurerar den efter dina behov.

Grunderna i EventPipe

EventPipe aggregerar händelser som genereras av körningskomponenter , till exempel just-in-time-kompilatorn eller skräpinsamlaren, och händelser som skrivits från EventSource-instanser i biblioteken och användarkoden.

Händelserna serialiseras sedan i filformatet .nettrace och kan skrivas direkt till en fil eller strömmas via en diagnostikport för out-of-process-förbrukning.

Mer information om EventPipe-serialiseringsformatet finns i dokumentationen om EventPipe-format.

EventPipe jämfört med ETW/perf_events

EventPipe är en del av .NET-körningen och är utformad för att fungera på samma sätt på alla plattformar som .NET Core stöder. På så sätt kan spårningsverktyg baserade på EventPipe, till exempel dotnet-counters, dotnet-gcdumpoch dotnet-trace, fungera sömlöst mellan plattformar.

Men eftersom EventPipe är en inbyggd körningskomponent är dess omfång begränsat till hanterad kod och själva körningen. EventPipe-händelser inkluderar stacktraces med endast information om hanterad kodram. Om du vill att händelser som genereras från andra ohanterade bibliotek i användarläge, CPU-sampling för intern kod eller kernelhändelser ska du använda OS-specifika spårningsverktyg som ETW eller perf_events. I Linux hjälper verktyget perfcollect till att automatisera användningen av perf_events och LTTng.

En annan stor skillnad mellan EventPipe och ETW/perf_events är krav på administratörs-/rotprivilegier. Om du vill spåra ett program med ETW eller perf_events måste du vara administratör/rot. Med EventPipe kan du spåra program så länge spårningen (till exempel dotnet-trace) körs som samma användare som användaren som startade programmet.

Följande tabell är en sammanfattning av skillnaderna mellan EventPipe och ETW/perf_events.

Funktion EventPipe ETW perf_events
Flera plattformar Ja Nej (endast i Windows) Nej (endast på Linux-distributioner som stöds)
Kräv administratörs-/rotprivilegier Nej Ja Ja
Kan hämta OS/kernel-händelser Nej Ja Ja
Kan lösa interna samtalstackar Nej Ja Ja

Använda EventPipe för att spåra ditt .NET-program

Du kan använda EventPipe för att spåra ditt .NET-program på många sätt:

När du har skapat en nettrace fil som innehåller dina EventPipe-händelser kan du visa filen i PerfView eller Visual Studio. På icke-Windows-plattformar kan du konvertera nettrace filen till ett speedscope eller Chromium spårningsformat med hjälp av kommandot dotnet-trace convert och visa den med speedscope eller Chrome DevTools.

Du kan också analysera EventPipe-spårningar programmatiskt med TraceEvent.

Verktyg som använder EventPipe

Det här är det enklaste sättet att använda EventPipe för att spåra ditt program. Mer information om hur du använder vart och ett av dessa verktyg finns i dokumentationen för varje verktyg.

  • med dotnet-counters kan du övervaka och samla in olika mått som genereras av .NET-körnings- och kärnbiblioteken, samt anpassade mått som du kan skriva.

  • med dotnet-gcdump kan du samla in GC-heapdumpar med aktiva processer för att analysera ett programs hanterade heap.

  • med dotnet-trace kan du samla in spårningar av program för att analysera prestanda.

Spåra med hjälp av miljövariabler

Den bästa mekanismen för att använda EventPipe är att använda dotnet-trace eller Microsoft.Diagnostics.NETCore.Client-biblioteket .

Du kan dock använda följande miljövariabler för att konfigurera en EventPipe-session i en app och låta den skriva spårningen direkt till en fil. Avsluta programmet om du vill stoppa spårningen.

  • DOTNET_EnableEventPipe: Ställ in detta på 1 för att starta en EventPipe-session som skriver direkt till en fil. Standardvärdet är 0.

  • DOTNET_EventPipeOutputPath: Sökvägen till händelsepipe-spårningsfilen för utdata när den är konfigurerad att köras via DOTNET_EnableEventPipe. Standardvärdet är trace.nettrace, som skapas i samma katalog som appen körs från.

    Kommentar

    Sedan .NET 6 ersätts instanser av strängen {pid} i DOTNET_EventPipeOutputPath med process-ID:t för den process som spåras.

  • DOTNET_EventPipeCircularMB: Ett hexadecimalt värde som representerar storleken på EventPipes interna buffert i megabyte. Det här konfigurationsvärdet används bara när EventPipe är konfigurerat att köras via DOTNET_EnableEventPipe. Standardbuffertstorleken är 1 024 MB, vilket innebär att den här miljövariabeln är inställd på 400, sedan == 0x4001024 .

    Kommentar

    Om målprocessen skriver händelser för ofta kan den flöda över den här bufferten och vissa händelser kan tas bort. Om för många händelser tas bort ökar du buffertstorleken för att se om antalet borttagna händelser minskar. Om antalet borttagna händelser inte minskar med en större buffertstorlek kan det bero på att en långsam läsare förhindrar att målprocessens buffertar töms.

  • DOTNET_EventPipeProcNumbers: Ange detta för 1 att aktivera insamling av processornummer i EventPipe-händelserubriker. Standardvärdet är 0.

  • DOTNET_EventPipeConfig: Konfigurerar konfigurationen av EventPipe-sessionen när du startar en EventPipe-session med DOTNET_EnableEventPipe. Syntaxen ser ut så här:

    <provider>:<keyword>:<level>

    Du kan också ange flera providers genom att sammanfoga dem med ett kommatecken:

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

    Om den här miljövariabeln inte har angetts men EventPipe är aktiverad av DOTNET_EnableEventPipebörjar den spåra genom att aktivera följande providers med följande nyckelord och nivåer:

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

    Mer information om några av de välkända leverantörerna i .NET finns i Välkända händelseleverantörer.

Kommentar

.NET 6 standardiserar på prefixet DOTNET_ i stället COMPlus_ för för miljövariabler som konfigurerar .NET-körningsbeteende. Prefixet COMPlus_ fortsätter dock att fungera. Om du använder en tidigare version av .NET-körningen bör du fortfarande använda prefixet COMPlus_ för miljövariabler.