EventPipe

  • Článek

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

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/LTTng

EventPipe je součástí modulu runtime .NET (CoreCLR) a je navržený tak, aby fungoval stejným způsobem na všech platformách, které .NET Core podporuje. 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. EventPipe se nedá použít ke sledování některých událostí nižší úrovně, jako je překlad nativního zásobníku kódu nebo získávání různých událostí jádra. Pokud ve své aplikaci používáte interoperabilitu C/C++ nebo chcete trasovat samotný modul runtime (který je napsaný v jazyce C++), nebo chcete podrobnější diagnostiku chování aplikace, která vyžaduje události jádra (tj. události přepínání kontextu nativních vláken), měli byste použít etW nebo perf/LTTng.

Dalším významným rozdílem mezi EventPipe a ETW/LTTng je požadavek na oprávnění správce/kořen. Pokud chcete trasovat aplikaci pomocí Trasování událostí pro Windows nebo LTTng, musíte být správcem nebo rootem. 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 EventPipe a ETW/LTTng.

Funkce EventPipe Trasování událostí pro Windows LTTng
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í.