Wprowadzenie do usługi EventSource
Ten artykuł dotyczy: ✔️ .NET Core 3.1 i nowsze wersje ✔️ .NET Framework 4.5 lub nowsze wersje
W tym przewodniku pokazano, jak rejestrować nowe zdarzenie przy użyciu System.Diagnostics.Tracing.EventSource, zbierać zdarzenia w pliku śledzenia, wyświetlać ślad i rozumieć podstawowe pojęcia dotyczące źródła zdarzeń.
Notatka
Wiele technologii integrujących się z usługą EventSource używa terminów "Śledzenie" i "Ślady" zamiast "Rejestrowanie" i "Dzienniki". Znaczenie jest takie samo tutaj.
Rejestrowanie zdarzenia
Celem usługi EventSource jest umożliwienie deweloperom platformy .NET pisania kodu takiego jak w celu zarejestrowania zdarzenia:
DemoEventSource.Log.AppStarted("Hello World!", 12);
Ten wiersz kodu zawiera obiekt rejestrowania (DemoEventSource.Log), metodę reprezentującą zdarzenie do rejestrowania (AppStarted) i opcjonalnie niektóre silnie typizowane parametry zdarzeń (HelloWorld! i 12). Brak poziomów szczegółowości, identyfikatorów zdarzeń, szablonów wiadomości ani żadnych innych elementów, które nie muszą znajdować się w miejscu wywołania. Wszystkie te inne informacje o zdarzeniach są zapisywane przez zdefiniowanie nowej klasy pochodzącej z System.Diagnostics.Tracing.EventSource.
Oto kompletny minimalny przykład:
using System.Diagnostics.Tracing;
namespace EventSourceDemo
{
public static class Program
{
public static void Main(string[] args)
{
DemoEventSource.Log.AppStarted("Hello World!", 12);
}
}
[EventSource(Name = "Demo")]
class DemoEventSource : EventSource
{
public static DemoEventSource Log { get; } = new DemoEventSource();
[Event(1)]
public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
}
}
Klasa DemoEventSource deklaruje metodę dla każdego typu zdarzenia, które chcesz zarejestrować. W tym przypadku jedno zdarzenie o nazwie "AppStarted" jest definiowane przez metodę AppStarted(). Za każdym razem, gdy kod wywołuje metodę AppStarted, w śladzie zostanie zarejestrowane inne zdarzenie AppStarted, jeśli zdarzenie jest włączone. Oto niektóre dane, które można przechwycić przy użyciu każdego zdarzenia:
- Nazwa zdarzenia — nazwa identyfikująca rodzaj zarejestrowanego zdarzenia. Nazwa zdarzenia będzie taka sama jak nazwa metody "AppStarted" w tym przypadku.
- Identyfikator zdarzenia — identyfikator liczbowy identyfikujący rodzaj zarejestrowanego zdarzenia. Pełni to podobną rolę do nazwy, ale może pomóc w szybkim zautomatyzowanym przetwarzaniu dzienników. Zdarzenie AppStarted ma identyfikator 1 określony w EventAttribute.
- Nazwa źródła — nazwa źródła zdarzeń zawierającego zdarzenie. Jest on używany jako przestrzeń nazw dla zdarzeń. Nazwy zdarzeń i identyfikatory muszą być unikatowe tylko w zakresie ich źródła. Tutaj źródło ma nazwę "Demo", określone w EventSourceAttribute definicji klasy. Nazwa źródła jest również często określana jako nazwa dostawcy.
- Argumenty — wszystkie wartości argumentów metody są serializowane.
- Inne informacje: zdarzenia mogą również zawierać znaczniki czasu, identyfikatory wątków, identyfikatory procesora, identyfikatory działań, ślady stosu i metadane zdarzeń, takie jak szablony komunikatów, poziomy szczegółowości i słowa kluczowe.
Aby uzyskać więcej informacji i najlepszych rozwiązań dotyczących tworzenia zdarzeń, zobacz Instrumenting code to create events.
Zbierz i wyświetl plik śledzenia
W kodzie nie ma wymaganej konfiguracji, która opisuje, które zdarzenia powinny być włączone, gdzie powinny być wysyłane zarejestrowane dane lub w jakim formacie powinny być przechowywane dane. Jeśli teraz uruchomisz aplikację, nie będzie ona domyślnie generować żadnego pliku śledzenia. Usługa EventSource używa wzorca publikowania-subskrybowania , który wymaga od subskrybentów wskazania zdarzeń, które powinny być włączone i do kontrolowania wszystkich serializacji dla subskrybowanych zdarzeń. EventSource ma integracje do subskrybowania z Event Tracing for Windows (ETW) i EventPipe (tylko .NET Core). Subskrybentów niestandardowych można również utworzyć za pomocą interfejsu API System.Diagnostics.Tracing.EventListener.
Pokaz ten przedstawia przykład EventPipe dla aplikacji .NET Core. Aby dowiedzieć się więcej o innych opcjach, zobacz Zbieranie i wyświetlanie śladów zdarzeń. EventPipe to otwarta i międzyplatformowa technologia śledzenia wbudowana w środowisko uruchomieniowe platformy .NET Core, która zapewnia deweloperom platformy .NET narzędzia do zbierania śladów oraz przenośny, kompaktowy format śledzenia (*.nettrace). dotnet-trace to narzędzie wiersza polecenia, które zbiera ślady usługi EventPipe.
- Pobierz i zainstaluj dotnet-trace.
- Skompiluj aplikację konsolową powyżej. W tym demo założono, że aplikacja ma nazwę EventSourceDemo.exe i znajduje się w bieżącym katalogu. W wierszu polecenia uruchom polecenie:
>dotnet-trace collect --providers Demo -- EventSourceDemo.exe
Powinno to spowodować wyświetlenie danych wyjściowych podobnych do:
Provider Name Keywords Level Enabled By
Demo 0xFFFFFFFFFFFFFFFF Verbose(5) --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_20220303_001619.nettrace
[00:00:00:00] Recording trace 0.00 (B)
Press <Enter> or <Ctrl+C> to exit...
Trace completed.
Ten proces uruchomił EventSourceDemo.exe ze wszystkimi zdarzeniami w EventSource 'Demo' włączonymi i wygenerowało plik śledzenia EventSourceDemo.exe_20220303_001619.nettrace.
Otwarcie pliku w programie Visual Studio pokazuje zarejestrowane zdarzenia.
W widoku listy możesz zobaczyć, że pierwszym zdarzeniem jest zdarzenie Demo/AppStarted. Kolumna tekstu zawiera zapisane argumenty, kolumna znacznika czasu pokazuje, że zdarzenie miało miejsce 27 ms po rozpoczęciu rejestrowania, a po prawej stronie widać stos wywołań. Inne zdarzenia są automatycznie włączane w każdym śledzeniu zbieranym przez dotnet-trace, chociaż mogą być ignorowane i filtrowane z widoku interfejsu użytkownika, jeśli rozpraszają uwagę. Te dodatkowe zdarzenia przechwytują pewne informacje o procesie i kodzie jitted, co umożliwia programowi Visual Studio odtworzenie śladów stosu zdarzeń.
