Udostępnij przez

EventPipe

  • Artykuł

EventPipe to składnik środowiska uruchomieniowego, który może służyć do zbierania danych śledzenia, podobnie jak ETW lub LTTng. Celem rozwiązania EventPipe jest umożliwienie deweloperom platformy .NET łatwego śledzenia aplikacji .NET bez konieczności polegania na składnikach natywnych dla systemu operacyjnego specyficznych dla platformy, takich jak ETW lub LTTng.

EventPipe jest mechanizmem wielu narzędzi diagnostycznych i może służyć do korzystania z zdarzeń emitowanych przez środowisko uruchomieniowe, a także zdarzeń niestandardowych napisanych za pomocą usługi EventSource.

Ten artykuł zawiera ogólne omówienie usługi EventPipe. Opisano w nim, kiedy i jak używać rozwiązania EventPipe oraz jak skonfigurować go do najlepszych potrzeb.

EventPipe — podstawy

EventPipe agreguje zdarzenia emitowane przez składniki środowiska uruchomieniowego — na przykład kompilator Just-In-Time lub moduł odśmiecający pamięci — i zdarzenia zapisywane z wystąpień usługi EventSource w bibliotekach i kodzie użytkownika.

Zdarzenia są następnie serializowane w .nettrace formacie pliku i mogą być zapisywane bezpośrednio w pliku lub przesyłane strumieniowo za pośrednictwem portu diagnostycznego do użycia poza procesem.

Aby dowiedzieć się więcej na temat formatu serializacji EventPipe, zapoznaj się z dokumentacją formatu EventPipe.

EventPipe a ETW/LTTng

EventPipe jest częścią środowiska uruchomieniowego platformy .NET (CoreCLR) i jest przeznaczony do pracy w taki sam sposób na wszystkich platformach .NET Core. Dzięki temu narzędzia do śledzenia oparte na interfejsie EventPipe, takim jak dotnet-counters, dotnet-gcdumpi dotnet-trace, bezproblemowo działają na różnych platformach.

Jednak ponieważ EventPipe jest wbudowanym składnikiem środowiska uruchomieniowego, jego zakres jest ograniczony do kodu zarządzanego i samego środowiska uruchomieniowego. Nie można używać elementu EventPipe do śledzenia niektórych zdarzeń niższego poziomu, takich jak rozpoznawanie natywnego stosu kodu lub pobieranie różnych zdarzeń jądra. Jeśli używasz międzyoperacyjności języka C/C++ w aplikacji lub chcesz śledzić środowisko uruchomieniowe (napisane w języku C++) lub chcesz uzyskać dokładnszą diagnostykę zachowania aplikacji, która wymaga zdarzeń jądra (czyli zdarzeń przełączania kontekstu natywnego wątku), należy użyć funkcji ETW lub wydajności/LTTng.

Kolejną główną różnicą między elementami EventPipe i ETW/LTTng jest wymaganie uprawnień administratora/głównego. Aby śledzić aplikację przy użyciu funkcji ETW lub LTTng, musisz być administratorem/katalogiem głównym. Za pomocą interfejsu EventPipe można śledzić aplikacje, o ile śledzenie (na przykład dotnet-trace) jest uruchamiane jako ten sam użytkownik, co użytkownik, który uruchomił aplikację.

Poniższa tabela zawiera podsumowanie różnic między elementami EventPipe i ETW/LTTng.

Funkcja EventPipe ETW LTTng
Między platformami Tak Nie (tylko w systemie Windows) Nie (tylko w obsługiwanych dystrybucjach systemu Linux)
Wymagaj uprawnień administratora/głównego Nie. Tak Tak
Może pobierać zdarzenia systemu operacyjnego/jądra Nie. Tak Tak
Może rozpoznawać natywne stosy wywołań Nie. Tak Tak

Śledzenie aplikacji .NET za pomocą narzędzia EventPipe

Narzędzie EventPipe umożliwia śledzenie aplikacji .NET na wiele sposobów:

Po utworzeniu pliku zawierającego nettrace zdarzenia EventPipe możesz wyświetlić plik w programie PerfView lub Visual Studio. Na platformach innych niż Windows można przekonwertować nettrace plik na speedscope format lub Chromium śledzenia za pomocą polecenia dotnet-trace convert i wyświetlić go za pomocą speedscope lub Chrome DevTools.

Możesz również programowo analizować ślady eventPipe za pomocą funkcji TraceEvent.

Narzędzia korzystające z elementu EventPipe

Jest to najprostszy sposób śledzenia aplikacji za pomocą usługi EventPipe. Aby dowiedzieć się więcej na temat korzystania z każdego z tych narzędzi, zapoznaj się z dokumentacją każdego narzędzia.

  • dotnet-counters umożliwia monitorowanie i zbieranie różnych metryk emitowanych przez środowisko uruchomieniowe platformy .NET i biblioteki podstawowe, a także metryki niestandardowe, które można napisać.

  • dotnet-gcdump umożliwia zbieranie zrzutów sterty GC procesów na żywo na potrzeby analizowania zarządzanej sterty aplikacji.

  • dotnet-trace umożliwia zbieranie śladów aplikacji do analizowania pod kątem wydajności.

Śledzenie przy użyciu zmiennych środowiskowych

Preferowanym mechanizmem używania elementu EventPipe jest użycie biblioteki dotnet-trace lub Microsoft.Diagnostics.NETCore.Client .

Można jednak użyć następujących zmiennych środowiskowych, aby skonfigurować sesję EventPipe w aplikacji i zapisać ślad bezpośrednio w pliku. Aby zatrzymać śledzenie, zamknij aplikację.

  • DOTNET_EnableEventPipe: ustaw wartość na , aby 1 uruchomić sesję eventPipe, która zapisuje bezpośrednio w pliku. Domyślna wartość to 0.

  • DOTNET_EventPipeOutputPath: ścieżka do wyjściowego pliku śledzenia EventPipe, gdy jest skonfigurowany do uruchamiania za pomocą polecenia DOTNET_EnableEventPipe. Wartość domyślna to trace.nettrace, która zostanie utworzona w tym samym katalogu, z którego jest uruchomiona aplikacja.

    Uwaga

    Ponieważ platforma .NET 6, wystąpienia ciągu {pid} w pliku DOTNET_EventPipeOutputPath są zastępowane identyfikatorem procesu śledzonego.

  • DOTNET_EventPipeCircularMB: wartość szesnastkowa reprezentująca rozmiar wewnętrznego buforu eventPipe w megabajtach. Ta wartość konfiguracji jest używana tylko wtedy, gdy parametr EventPipe jest skonfigurowany do uruchamiania za pomocą polecenia DOTNET_EnableEventPipe. Domyślny rozmiar buforu to 1024 MB, co przekłada się na ustawioną zmienną środowiskową na 400, ponieważ == 0x4001024 .

    Uwaga

    Jeśli proces docelowy zapisuje zdarzenia zbyt często, może przepełnić ten bufor, a niektóre zdarzenia mogą zostać porzucone. Jeśli zbyt wiele zdarzeń zostanie porzuconych, zwiększ rozmiar buforu, aby sprawdzić, czy liczba porzuconych zdarzeń zmniejsza się. Jeśli liczba porzuconych zdarzeń nie zmniejszy się z większym rozmiarem buforu, może to być spowodowane powolnym czytnikiem uniemożliwiającym opróżnianie buforów procesu docelowego.

  • DOTNET_EventPipeProcNumbers: ustaw tę opcję, aby 1 włączyć przechwytywanie numerów procesorów w nagłówkach zdarzeń EventPipe. Domyślna wartość to 0.

  • DOTNET_EventPipeConfig: Konfiguruje konfigurację sesji EventPipe podczas uruchamiania sesji EventPipe za pomocą polecenia DOTNET_EnableEventPipe. Składnia wygląda następująco:

    <provider>:<keyword>:<level>

    Można również określić wielu dostawców, łącząc ich z przecinkami:

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

    Jeśli ta zmienna środowiskowa nie jest ustawiona, ale parametr EventPipe jest włączony przez DOTNET_EnableEventPipeprogram , rozpocznie śledzenie, włączając następujących dostawców z następującymi słowami kluczowymi i poziomami:

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

    Aby dowiedzieć się więcej na temat niektórych znanych dostawców na platformie .NET, zapoznaj się z tematem Dobrze znani dostawcy zdarzeń.

Uwaga

Program .NET 6 standardizuje prefiks DOTNET_ zamiast COMPlus_ zmiennych środowiskowych, które konfigurują zachowanie czasu wykonywania platformy .NET. COMPlus_ Jednak prefiks będzie nadal działać. Jeśli używasz poprzedniej wersji środowiska uruchomieniowego platformy .NET, nadal należy użyć prefiksu COMPlus_ dla zmiennych środowiskowych.