EventPipe

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

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

EventPipe jest częścią środowiska uruchomieniowego platformy .NET i jest przeznaczony do pracy w taki sam sposób na wszystkich platformach . NET Core obsługuje. 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. Zdarzenia EventPipe obejmują stostraces tylko z informacjami o ramce kodu zarządzanego. Jeśli chcesz, aby zdarzenia generowane z innych niezarządzanych bibliotek trybu użytkownika, próbkowanie procesora CPU dla kodu natywnego lub zdarzenia jądra, należy użyć narzędzi śledzenia specyficznych dla systemu operacyjnego, takich jak ETW lub perf_events. W systemie Linux narzędzie perfcollect pomaga zautomatyzować korzystanie z perf_events i LTTng.

Inną główną różnicą między elementami EventPipe i ETW/perf_events jest wymaganie uprawnień administratora/głównego. Aby śledzić aplikację przy użyciu funkcji ETW lub perf_events 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/perf_events.

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

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

• Użyj jednego z narzędzi diagnostycznych opartych na interfejsie EventPipe.

• Użyj biblioteki Microsoft.Diagnostics.NETCore.Client , aby napisać własne narzędzie do konfigurowania i uruchamiania sesji eventPipe.

• Użyj zmiennych środowiskowych, aby uruchomić aplikację EventPipe.

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 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ń.