Sdílet prostřednictvím

EventPipe

  • Článek

EventPipe je komponenta modulu runtime, která se dá použít ke shromažďování dat trasování, podobně jako trasování událostí pro Windows nebo perf_events. Cílem eventPipe je umožnit vývojářům platformy .NET snadné trasování aplikací .NET, aniž by museli spoléhat na komponenty s vysokou úrovní oprávnění specifické pro platformu, jako jsou ETW nebo perf_events.

EventPipe je mechanismus za mnoha diagnostickými nástroji a lze ho použít k využívání událostí generovaných modulem runtime i vlastních událostí zapsaných pomocí EventSource.

Tento článek je přehledem třídy EventPipe na vysoké úrovni. Popisuje, kdy a jak používat EventPipe a jak ho nakonfigurovat tak, aby co nejlépe vyhovoval vašim potřebám.

Základy eventPipe

EventPipe agreguje události generované komponentami modulu runtime – například kompilátor Just-In-Time nebo uvolňování paměti – a události zapsané z instancí EventSource v knihovnách a uživatelském kódu.

Události se pak serializují ve .nettrace formátu souboru a lze je zapsat přímo do souboru nebo streamovat přes diagnostický port pro spotřebu mimo proces.

Další informace o formátu serializace EventPipe najdete v dokumentaci k formátu EventPipe.

EventPipe vs. ETW/perf_events

EventPipe je součástí modulu runtime .NET a je navržený tak, aby fungoval stejným způsobem napříč všemi platformami, které podporuje .NET Core. Díky tomu mohou nástroje pro trasování založené na eventPipe, jako dotnet-countersje například , dotnet-gcdumpa dotnet-trace, bezproblémově fungovat na různých platformách.

Vzhledem k tomu, že EventPipe je předdefinovaná komponenta modulu runtime, je jeho obor omezen na spravovaný kód a samotný modul runtime. Události EventPipe zahrnují pouze stacktraces s informacemi o rámci spravovaného kódu. Pokud chcete, aby události generované z jiných nespravovaných knihoven uživatelského režimu, vzorkování procesoru pro nativní kód nebo události jádra, měli byste použít nástroje pro trasování specifické pro operační systém, jako jsou trasovací nástroje pro Windows nebo perf_events. Nástroj perfcollect v Linuxu pomáhá automatizovat používání perf_events a LTTng.

Dalším významným rozdílem mezi EventPipe a ETW/perf_events je požadavek na oprávnění správce/root. Pokud chcete trasovat aplikaci pomocí Trasování událostí pro Windows nebo perf_events musíte být správcem nebo kořenem. Pomocí eventPipe můžete trasovat aplikace, pokud je tracer (například dotnet-trace) spuštěný jako stejný uživatel jako uživatel, který aplikaci spustil.

Následující tabulka obsahuje souhrn rozdílů mezi událostmi EventPipe a ETW/perf_events.

Funkce EventPipe Trasování událostí pro Windows perf_events
Mezi platformami Ano Ne (jenom ve Windows) Ne (pouze u podporovaných distribucí Linuxu)
Vyžadování oprávnění správce nebo kořenového adresáře No Ano Yes
Může získat události operačního systému nebo jádra No Ano Yes
Dokáže vyřešit nativní volání No Ano Yes

Trasování aplikace .NET pomocí EventPipe

EventPipe můžete použít k trasování aplikace .NET mnoha způsoby:

Po vytvoření nettrace souboru, který obsahuje události EventPipe, můžete soubor zobrazit v nástroji PerfView nebo v sadě Visual Studio. Na jiných platformách než Windows můžete soubor převést nettrace do speedscope formátu trasování pomocí Chromium příkazu dotnet-trace convert a zobrazit ho pomocí speedscope nebo Chrome DevTools.

Trasování EventPipe můžete analyzovat také programově pomocí TraceEventu.

Nástroje, které používají EventPipe

Toto je nejjednodušší způsob, jak pomocí eventPipe trasovat aplikaci. Další informace o tom, jak jednotlivé nástroje používat, najdete v dokumentaci jednotlivých nástrojů.

Trasování pomocí proměnných prostředí

Upřednostňovaným mechanismem pro použití eventPipe je použití dotnet-trace nebo knihovny Microsoft.Diagnostics.NETCore.Client .

Následující proměnné prostředí ale můžete použít k nastavení relace EventPipe v aplikaci a k zápisu trasování přímo do souboru. Pokud chcete trasování zastavit, ukončete aplikaci.

  • DOTNET_EnableEventPipe: Nastavte ji tak, aby 1 se spustila relace EventPipe, která zapisuje přímo do souboru. Výchozí hodnota je 0.

  • DOTNET_EventPipeOutputPath: Cesta k výstupnímu trasovacímu souboru EventPipe, když je nakonfigurovaná tak, aby běžela přes DOTNET_EnableEventPipe. Výchozí hodnota je trace.nettrace, která se vytvoří ve stejném adresáři, ze kterého aplikace běží.

    Poznámka:

    Vzhledem k tomu, že .NET 6 jsou instance řetězce {pid} v DOTNET_EventPipeOutputPath nahrazeny ID procesu trasovaného procesu.

  • DOTNET_EventPipeCircularMB: Šestnáctková hodnota, která představuje velikost interní vyrovnávací paměti EventPipe v megabajtech. Tato hodnota konfigurace se používá pouze v případě, že je eventPipe nakonfigurovaný tak, aby běžel přes DOTNET_EnableEventPipe. Výchozí velikost vyrovnávací paměti je 1024 MB, která se překládá na tuto proměnnou prostředí nastavenou na 400, protože == 0x4001024 .

    Poznámka:

    Pokud cílový proces zapisuje události příliš často, může přetéct tuto vyrovnávací paměť a některé události se můžou vynechat. Pokud se zahodí příliš mnoho událostí, zvětšete velikost vyrovnávací paměti, abyste zjistili, jestli se počet vynechaných událostí snižuje. Pokud se počet vynechaných událostí nezmenší s větší velikostí vyrovnávací paměti, může to být způsobeno pomalým čtenářem, který brání v vyprázdnění vyrovnávací paměti cílového procesu.

  • DOTNET_EventPipeProcNumbers: Nastavte to tak, aby 1 povolte zachytávání čísel procesorů v hlavičce událostí EventPipe. Výchozí hodnota je 0.

  • DOTNET_EventPipeConfig: Nastaví konfiguraci relace EventPipe při spuštění relace EventPipe s DOTNET_EnableEventPipe. Syntaxe je následující:

    <provider>:<keyword>:<level>

    Můžete také zadat více poskytovatelů tak, že je zřetězením čárkami:

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

    Pokud tato proměnná prostředí není nastavená, ale eventPipe je povolena DOTNET_EnableEventPipe, zahájí trasování povolením následujících zprostředkovatelů s následujícími klíčovými slovy a úrovněmi:

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

    Další informace o některých známých poskytovatelích v .NET najdete v části Známé zprostředkovatele událostí.

Poznámka:

.NET 6 standardizuje předponu DOTNET_ místo COMPlus_ proměnných prostředí, které konfigurují chování za běhu .NET. Předpona COMPlus_ ale bude i nadále fungovat. Pokud používáte předchozí verzi modulu runtime .NET, měli byste stále používat předponu COMPlus_ pro proměnné prostředí.