Udostępnij za pośrednictwem

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 stojącym za wieloma narzędziami diagnostycznymi i może być używany do odbierania zdarzeń emitowanych przez środowisko uruchomieniowe, a także zdarzeń niestandardowych tworzonych za pomocą 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 odzyskiwacz pamięci — oraz zdarzenia zapisywane z instancji 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 NetTrace, zobacz dokumentację formatu NetTrace.

EventPipe kontra ETW/perf_events

EventPipe jest częścią .NET runtime i został zaprojektowany, aby działać w taki sam sposób na wszystkich platformach, które wspiera .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. Bez użycia innych narzędzi do śledzenia, zdarzenia EventPipe zawierają ślady stosu tylko z informacjami o ramach kodu zarządzanego. Aby uzyskać zdarzenia z innych niezarządzanych bibliotek trybu użytkownika, próbki wydajności procesora dla kodu natywnego lub zdarzenia jądra, użyj narzędzi do ś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.

Począwszy od platformy .NET 10, EventPipe w systemie Linux może emitować zdarzenia jako user_events, umożliwiając zbieranie zdarzeń zarządzanych, zdarzeń systemu operacyjnego/jądra i natywnych stosów wywołań w jednym ujednoliconym śladzie. Ten tryb wymaga uprawnień administratora/głównego i jądra systemu Linux w wersji 6.4 lub nowszej. Aby uzyskać więcej informacji, zobacz dotnet-trace collect-linux.

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 ETW lub perf_events, musisz być administratorem/użytkownikiem root. Korzystając z standardowego EventPipe, można śledzić aplikacje, pod warunkiem że proces śledzenia (na przykład dotnet-trace) jest uruchamiany przez tego samego użytkownika, który uruchomił aplikację. Opisany wcześniej tryb EventPipe (user_events) wymaga uprawnień administratora/głównego, ponieważ współdziała z infrastrukturą śledzenia na poziomie systemu operacyjnego.

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

Funkcja EventPipe EventPipe (zdarzenia_użytkownika) ETW perf_events
Wieloplatformowy Tak Nie (tylko w obsługiwanych dystrybucjach systemu Linux) Nie (tylko w systemie Windows) Nie (tylko w obsługiwanych dystrybucjach systemu Linux)
Wymagaj uprawnień administratora/głównego Nie. Tak Tak Tak
Może pobierać zdarzenia systemu operacyjnego/jądra Nie. Tak Tak Tak
Może rozwiązywać natywne stosy wywołań Nie. Tak 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ć plik nettrace na format speedscope 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 z aktualnie działających procesów do analizy 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 EventPipe jest użycie narzędzia dotnet-trace lub biblioteki 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 to na 1, aby uruchomić sesję EventPipe zapisującą bezpośrednio do pliku. Domyślna wartość to 0.

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

    Uwaga

    Od .NET 6, wystąpienia ciągu {pid} w 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 ustawienie zmiennej środowiskowej na 400, ponieważ 0x400 == 1024.

    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ę przy większym rozmiarze buforu, może to być spowodowane powolnym odczytem uniemożliwiającym opróżnianie buforów procesu docelowego.

  • DOTNET_EventPipeProcNumbers: Ustaw to na 1, aby 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 Dobrymi dostawcami zdarzeń.

  • Last updated on