Zbieranie i wyświetlanie śladów źródła zdarzeń

Artykuł
05/09/2023

Ten artykuł dotyczy: ✔️ .NET Core 3.1 i nowsze wersje ✔️ .NET Framework 4.5 i nowszych wersjach

W przewodniku Wprowadzenie pokazano, jak utworzyć minimalne źródło zdarzeń i zebrać zdarzenia w pliku śledzenia. W tym samouczku pokazano, jak różne narzędzia mogą konfigurować, które zdarzenia są zbierane w śladzie, a następnie wyświetlać ślady.

Przykładowa aplikacja

Użyjesz następującej przykładowej aplikacji, która generuje zdarzenia dla tego samouczka. Skompiluj aplikację konsolową platformy .NET zawierającą następujący kod:

using System.Diagnostics.Tracing;

namespace EventSourceDemo
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            DemoEventSource.Log.AppStarted("Hello World!", 12);
            DemoEventSource.Log.DebugMessage("Got here");
            DemoEventSource.Log.DebugMessage("finishing startup");
            DemoEventSource.Log.RequestStart(3);
            DemoEventSource.Log.RequestStop(3);
        }
    }

    [EventSource(Name = "Demo")]
    class DemoEventSource : EventSource
    {
        public static DemoEventSource Log { get; } = new DemoEventSource();

        [Event(1, Keywords = Keywords.Startup)]
        public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
        [Event(2, Keywords = Keywords.Requests)]
        public void RequestStart(int requestId) => WriteEvent(2, requestId);
        [Event(3, Keywords = Keywords.Requests)]
        public void RequestStop(int requestId) => WriteEvent(3, requestId);
        [Event(4, Keywords = Keywords.Startup, Level = EventLevel.Verbose)]
        public void DebugMessage(string message) => WriteEvent(4, message);


        public class Keywords
        {
            public const EventKeywords Startup = (EventKeywords)0x0001;
            public const EventKeywords Requests = (EventKeywords)0x0002;
        }
    }
}

Konfigurowanie zdarzeń do zbierania

Większość narzędzi zbierania zdarzeń używa tych opcji konfiguracji, aby zdecydować, które zdarzenia powinny być uwzględnione w śladzie:

Nazwy dostawców — jest to lista co najmniej jednej nazwy źródła zdarzeń. Na tej liście można uwzględnić tylko zdarzenia zdefiniowane na liście EventSources. Aby zebrać zdarzenia z klasy DemoEventSource w poprzedniej przykładowej aplikacji, należy dołączyć nazwę źródła zdarzeń "Demo" na liście nazw dostawców.
Poziom szczegółowości zdarzeń — dla każdego dostawcy można zdefiniować poziom szczegółowości i zdarzenia o szczegółowości wyższej niż ten poziom zostanie wykluczony ze śledzenia. Jeśli określono, że dostawca "Demo" w poprzedniej przykładowej aplikacji powinien zbierać się na poziomie szczegółowości informacyjnej, zdarzenie DebugMessage zostanie wykluczone, ponieważ ma wyższy poziom. Określenie EventLevel wartości LogAlways(0) jest specjalnym przypadkiem wskazującym, że należy uwzględnić zdarzenia dowolnego poziomu szczegółowości.
Słowa kluczowe zdarzenia — dla każdego dostawcy można zdefiniować zestaw słów kluczowych i uwzględniane będą tylko zdarzenia oznaczone co najmniej jednym ze słów kluczowych. W przykładowej aplikacji powyżej, jeśli określono słowo kluczowe Startup, zostaną uwzględnione tylko zdarzenia AppStarted i DebugMessage. Jeśli nie określono żadnych słów kluczowych, jest to specjalny przypadek i oznacza, że należy uwzględnić zdarzenia z dowolnym słowem kluczowym.

Konwencje opisujące konfigurację dostawcy

Chociaż każde narzędzie określa własny interfejs użytkownika do ustawiania konfiguracji śledzenia, istnieje powszechna konwencja, która jest używana podczas określania konfiguracji jako ciągu tekstowego. Lista dostawców jest określana jako lista rozdzielana średnikami, a każdy element dostawcy na liście składa się z nazw, słów kluczowych i poziomów rozdzielonych dwukropkami. Na przykład "Demo:3:5" identyfikuje źródło zdarzeń o nazwie "Demo" z maską bitową słowa kluczowego 3 ( Startup bit i bit) oraz RequestsEventLevel 5, czyli Verbose. Wiele narzędzi pozwala również pominąć poziom i słowa kluczowe, jeśli nie jest wymagany żaden poziom lub filtrowanie słów kluczowych. Na przykład "Demo::5" tylko filtruje na poziomie, "Demo:3" tylko filtruje oparte na słowach kluczowych, a "Demo" nie wykonuje filtrowania na poziomie ani słowa kluczowego.

Visual Studio

Profiler programu Visual Studio obsługuje zbieranie i wyświetlanie śladów. Może również wyświetlać ślady, które zostały zebrane z wyprzedzeniem przez inne narzędzia, takie jak dotnet-trace.

Zbieranie śladu

Większość narzędzi profilowania programu Visual Studio używa wstępnie zdefiniowanych zestawów zdarzeń, które służą do określonego celu, takich jak analizowanie użycia procesora CPU lub alokacji. Aby zebrać ślad z dostosowanymi zdarzeniami, użyjesz narzędzia Podgląd zdarzeń .

Aby otworzyć profilera wydajności w programie Visual Studio, wybierz pozycję Alt+F2.
Zaznacz pole wyboru Podgląd zdarzeń .
Wybierz małą ikonę koła zębatego po prawej stronie Podgląd zdarzeń, aby otworzyć okno konfiguracji.

W poniższej tabeli Dodatkowe dostawcy dodaj wiersz dla każdego dostawcy, który chcesz skonfigurować, klikając pole wyboru Włączone , a następnie wprowadzając nazwę dostawcy, słowa kluczowe i poziom. Nie musisz wprowadzać identyfikatora GUID dostawcy; jest obliczana automatycznie.
Wybierz przycisk OK , aby potwierdzić ustawienia konfiguracji.
Wybierz pozycję Rozpocznij, aby rozpocząć uruchamianie aplikacji i zbieranie dzienników.
Wybierz pozycję Zatrzymaj zbieranie lub zamknij aplikację, aby zatrzymać zbieranie dzienników i pokazać zebrane dane.

Wyświetlanie śladu

Program Visual Studio może wyświetlać zebrane ślady lub wyświetlać ślady zebrane w innych narzędziach. Aby wyświetlić ślady z innych narzędzi, użyj pozycji Plik>otwórz i wybierz plik śledzenia w selektorze plików. Profiler programu Visual Studio obsługuje pliki etl (standardowy format ETW), pliki .nettrace (standardowy format eventPipe) i pliki diagsession (standardowy format programu Visual Studio). Aby uzyskać informacje na temat pracy z plikami śledzenia w programie Visual Studio, zobacz dokumentację programu Visual Studio.

Uwaga

Program Visual Studio automatycznie zbiera niektóre zdarzenia z etW lub EventPipe, nawet jeśli nie zostały jawnie skonfigurowane. Jeśli zdarzenia nie są rozpoznawane w kolumnie Nazwa dostawcy lub Nazwa zdarzenia i chcesz je odfiltrować, użyj ikony filtru po prawej stronie, aby wybrać tylko zdarzenia, które chcesz wyświetlić.

Narzędzie PerfView

PerfView to narzędzie wydajności utworzone przez zespół platformy .NET, które może zbierać i wyświetlać ślady ETW. Może również wyświetlać pliki śledzenia zebrane przez inne narzędzia w różnych formatach. W tym samouczku zbierzesz ślad ETW aplikacji demonstracyjnej , a następnie zbadasz zebrane zdarzenia w podglądzie zdarzeń programu PerfView.

Zbieranie śladu

Pobierz aplikację PerfView ze strony wydań. Ten samouczek został wykonany z programem PerfView w wersji 2.0.76, ale każda najnowsza wersja powinna działać.
Rozpocznij PerfView.exe z uprawnieniami administratora.

Uwaga

Zbieranie śladów ETW zawsze wymaga uprawnień administratora, jednak jeśli używasz tylko narzędzia PerfView do wyświetlania wstępnie istniejącego śledzenia, nie są potrzebne żadne specjalne uprawnienia.
Z menu Zbieranie wybierz pozycję Uruchom. Spowoduje to otwarcie nowego okna dialogowego, w którym wprowadzisz ścieżkę do aplikacji demonstracyjnej.
Aby skonfigurować zbierane zdarzenia, rozwiń pozycję Opcje zaawansowane w dolnej części okna dialogowego. W polu tekstowym Dodatkowi dostawcy wprowadź dostawców przy użyciu konwencjonalnego formatu tekstu opisanego wcześniej. W takim przypadku wprowadzasz wartość "Demo:1:4", co oznacza słowo kluczowe bit 1 (Startup zdarzenia) i czasownik 4 (Informational).
Aby uruchomić aplikację i rozpocząć zbieranie śladu, wybierz przycisk Uruchom polecenie . Po zakończeniu działania aplikacji ślad PerfViewData.etl jest zapisywany w bieżącym katalogu.

Wyświetlanie śladu

W głównym oknie rozwijanym pole tekstowe w lewym górnym rogu wybierz katalog zawierający plik śledzenia. Następnie kliknij dwukrotnie plik śledzenia w widoku drzewa poniżej.
Aby wyświetlić podgląd zdarzeń, kliknij dwukrotnie element Zdarzenia , który jest wyświetlany w widoku drzewa poniżej pliku śledzenia.
Wszystkie typy zdarzeń w śladzie są wyświetlane na liście po lewej stronie. Kliknij dwukrotnie typ zdarzenia, taki jak Demo\AppStarted, aby wyświetlić wszystkie zdarzenia tego typu w tabeli po prawej stronie.

Więcej tutaj

Aby dowiedzieć się więcej na temat korzystania z narzędzia PerfView, zobacz samouczki wideo narzędzia PerfView.

dotnet-trace

dotnet-trace to wieloplatformowe narzędzie wiersza polecenia, które może zbierać ślady z aplikacji platformy .NET Core przy użyciu śledzenia eventPipe . Nie obsługuje wyświetlania danych śledzenia, ale zbierane ślady mogą być wyświetlane przez inne narzędzia, takie jak PerfView lub Visual Studio. funkcja dotnet-trace obsługuje również konwertowanie domyślnych śladów formatu .nettrace na inne formaty, takie jak Chromium lub Speedscope.

Zbieranie śladu

Pobierz i zainstaluj narzędzie dotnet-trace.

W wierszu polecenia uruchom polecenie dotnet-trace collect :

E:\temp\EventSourceDemo\bin\Debug\net6.0>dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe

Powinno to spowodować wyświetlenie danych wyjściowych podobnych do następujących:

E:\temp\EventSourceDemo\bin\Debug\net6.0> dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe

Provider Name                           Keywords            Level               Enabled By
Demo                                    0x0000000000000001  Informational(4)    --providers

Launching: EventSourceDemo.exe
Process        : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe
Output File    : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe_20220317_021512.nettrace

[00:00:00:00]   Recording trace 0.00     (B)
Press <Enter> or <Ctrl+C> to exit...

Trace completed.

dotnet-trace używa konwencjonalnego formatu tekstowego do opisywania konfiguracji dostawcy w argumencie --providers . Aby uzyskać więcej opcji na temat pobierania śladów przy użyciu narzędzia dotnet-trace, zobacz dokumentację dotnet-trace.

Eventlistener

System.Diagnostics.Tracing.EventListener to interfejs API platformy .NET, który może być używany z procesu do odbierania wywołań zwrotnych dla zdarzeń generowanych przez element System.Diagnostics.Tracing.EventSource. Ten interfejs API może służyć do tworzenia niestandardowych narzędzi rejestrowania lub analizowania zdarzeń w pamięci bez serializacji ich.

Aby użyć EventListenermetody , zadeklaruj typ pochodzący z EventListenerklasy , wywołaj polecenie EnableEvents w celu zasubskrybowania zdarzeń z dowolnego źródła zdarzeń i przesłonięć OnEventWrittenelement , który będzie wywoływany za każdym razem, gdy jest dostępne nowe zdarzenie. Często warto zastąpić OnEventSourceCreated , aby wykryć, które obiekty usługi EventSource istnieją, ale nie jest to wymagane. Poniżej przedstawiono przykładową EventListener implementację, która drukuje do konsoli po odebraniu komunikatów:

Dodaj ten kod do aplikacji demonstracyjnej.

class ConsoleWriterEventListener : EventListener
{
    protected override void OnEventSourceCreated(EventSource eventSource)
    {
        if(eventSource.Name == "Demo")
        {
            EnableEvents(eventSource, EventLevel.Informational);
        }
    }

    protected override void OnEventWritten(EventWrittenEventArgs eventData)
    {
        Console.WriteLine(eventData.TimeStamp + " " + eventData.EventName);
    }
}

Zmodyfikuj metodę, Main aby utworzyć wystąpienie nowego odbiornika.

public static void Main(string[] args)
{
    ConsoleWriterEventListener listener = new ConsoleWriterEventListener();

    DemoEventSource.Log.AppStarted("Hello World!", 12);
    DemoEventSource.Log.DebugMessage("Got here");
    DemoEventSource.Log.DebugMessage("finishing startup");
    DemoEventSource.Log.RequestStart(3);
    DemoEventSource.Log.RequestStop(3);
}

Skompiluj i uruchom aplikację. Wcześniej nie miał żadnych danych wyjściowych, ale teraz zapisuje zdarzenia w konsoli:
```
3/24/2022 9:23:35 AM AppStarted
3/24/2022 9:23:35 AM RequestStart
3/24/2022 9:23:35 AM RequestStop
```

Udostępnij za pośrednictwem

Zbieranie i wyświetlanie śladów źródła zdarzeń

Przykładowa aplikacja

Konfigurowanie zdarzeń do zbierania

Konwencje opisujące konfigurację dostawcy

Visual Studio

Zbieranie śladu

Wyświetlanie śladu

Narzędzie PerfView

Zbieranie śladu

Wyświetlanie śladu

Więcej tutaj

dotnet-trace

Zbieranie śladu

Eventlistener

Dodatkowe zasoby