Auflisten und Anzeigen von EventSource-Ablaufverfolgungen
Dieser Artikel gilt für: ✔️ .NET Core 3.1 und höhere Versionen ✔️ .NET Framework 4.5 und höhere Versionen
Im Leitfaden für erste Schritte haben Sie erfahren, wie Sie eine minimale EventSource-Instanz erstellen und Ereignisse in einer Ablaufverfolgungsdatei erfassen. Im vorliegenden Tutorial wird gezeigt, wie verschiedene Tools die Ereignisse konfigurieren, die in einer Ablaufverfolgung aufgelistet werden, und dann die Ablaufverfolgungen anzeigen.
Beispiel-App
Sie verwenden die folgende Beispiel-App, die Ereignisse für dieses Tutorial generiert. Kompilieren Sie eine .NET-Konsolenanwendung, die den folgenden Code enthält:
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;
}
}
}
Konfigurieren der aufzulistenden Ereignisse
Die meisten Tools zum Auflisten von Ereignissen verwenden diese Konfigurationsoptionen, um zu entscheiden, welche Ereignisse in eine Ablaufverfolgung einbezogen werden sollen:
- Anbieternamen: Dies ist eine Liste mit mindestens einem EventSource-Namen. Nur Ereignisse, die in EventSource-Instanzen in dieser Liste definiert sind, können einbezogen werden. Um Ereignisse aus der DemoEventSource-Klasse in der obigen Beispiel-App aufzulisten, müssen Sie den EventSource-Namen „Demo“ in die Liste der Anbieternamen einschließen.
- Ausführlichkeitsebene für Ereignisse: Sie können für jeden Anbieter eine Ausführlichkeitsebene definieren. Ereignisse mit einer Ausführlichkeit oberhalb dieser Ebene werden von der Ablaufverfolgung ausgeschlossen. Wenn Sie angegeben haben, dass der Anbieter „Demo“ in der obigen Beispiel-App auf der Ebene „Informational verbosity“ aufgelistet werden soll, wird das DebugMessage-Ereignis ausgeschlossen, da es eine höhere Ebene aufweist. EventLevel „LogAlways(0)“ ist ein Sonderfall, der angibt, dass Ereignisse aller Ausführlichkeitsebenen eingeschlossen werden sollen.
- Ereignisschlüsselwörter: Sie können für jeden Anbieter eine Reihe von Schlüsselwörtern definieren. Nur Ereignisse, die mit mindestens einem der Schlüsselwörter getaggt sind, werden eingeschlossen. Wenn Sie in der obigen Beispiel-App das Schlüsselwort „Startup“ angegeben haben, werden nur die Ereignisse „AppStarted“ und „DebugMessage“ einbezogen. Wenn keine Schlüsselwörter angegeben werden, ist dies ein Sonderfall und bedeutet, dass Ereignisse mit jedem Schlüsselwort eingeschlossen werden sollen.
Konventionen für die Beschreibung der Anbieterkonfiguration
Obwohl jedes Tool die Benutzeroberfläche zum Festlegen der Ablaufverfolgungskonfiguration selbst bestimmt, gibt es eine allgemeine Konvention, die viele Tools beim Angeben der Konfiguration als Textzeichenfolge verwenden. Die Liste der Anbieter wird als durch Semikolons getrennte Liste angegeben, und jedes Anbieterelement in der Liste besteht aus dem Namen, den Schlüsselwörtern und der Ebene, wobei die Werte durch Doppelpunkte getrennt sind. Beispielsweise identifiziert „Demo:3:5“ die EventSource-Instanz namens „Demo“ mit den Schlüsselwort-Bitmasken 3 (das Startup-Bit und das Requests-Bit) und EventLevel 5 (auf Verbose festgelegt). Bei vielen Tools können Sie Ebene und Schlüsselwörter auch weglassen, wenn keine Ebenen- oder Schlüsselwortfilterung gewünscht ist. Beispiele: Bei „Demo:5“ erfolgt nur eine ebenenbasierte Filterung, bei „Demo:3“ erfolgt nur eine schlüsselwortbasierte Filterung, und bei „Demo“ erfolgt weder eine ebenenbasierte noch eine schlüsselwortbasierte Filterung.
Visual Studio
Der Visual Studio-Profiler unterstützt sowohl das Auflisten als auch das Anzeigen von Ablaufverfolgungen. Damit lassen sich auch Ablaufverfolgungen anzeigen, die zuvor von anderen Tools wie z. B. dotnet-trace aufgelistet wurden.
Erfassen einer Ablaufverfolgung
Die meisten Profilerstellungstools von Visual Studio verwenden vordefinierte Ereignisse, die einem bestimmten Zweck dienen, z. B. zur Analyse von CPU-Auslastung oder -zuordnungen. Um eine Ablaufverfolgung mit angepassten Ereignissen aufzulisten, verwenden Sie die Ereignisanzeige.
Um den Leistungs-Profiler in Visual Studio zu öffnen, drücken Sie ALT+F2.
Aktivieren Sie das Kontrollkästchen Ereignisanzeige.
Wählen Sie das kleine Zahnradsymbol rechts neben der Ereignisanzeige aus, um das Konfigurationsfenster zu öffnen.
Fügen Sie in der Tabelle unter Zusätzliche Anbieter eine Zeile für jeden Anbieter hinzu, den Sie konfigurieren möchten. Klicken Sie dafür auf das Kontrollkästchen Aktiviert, und geben Sie dann den Anbieternamen, die Schlüsselwörter sowie die Ebene ein. Die Anbieter-GUID müssen Sie nicht eingeben, sie wird automatisch berechnet.
Wählen Sie OK aus, um die Konfigurationseinstellungen zu bestätigen.
Wählen Sie Start aus, um mit der Ausführung der App und dem Auflisten von Protokollen zu beginnen.
Wählen Sie Auflistung beenden aus, oder schließen Sie die App, um das Auflisten von Protokollen zu beenden und die aufgelisteten Daten anzuzeigen.
Anzeigen einer Ablaufverfolgung
Visual Studio kann Ablaufverfolgungen anzeigen, die es selbst aufgelistet hat oder die in anderen Tools aufgelistet wurden. Um Ablaufverfolgungen aus anderen Tools anzuzeigen, verwenden Sie Datei>Öffnen, und wählen Sie in der Dateiauswahl eine Ablaufverfolgungsdatei aus. Visual Studio-Profiler unterstützt .etl-Dateien (ETW-Standardformat), .nettrace-Dateien (EventPipe-Standardformat) und .diagsession-Dateien (Visual Studio-Standardformat). Informationen zum Arbeiten mit Ablaufverfolgungsdateien in Visual Studio finden Sie in der Visual Studio-Dokumentation.
Hinweis
Visual Studio listet einige Ereignisse automatisch aus ETW oder EventPipe auf, auch wenn sie nicht explizit konfiguriert wurden. Wenn Ereignisse angezeigt werden, die Sie in der Spalte „Anbietername“ oder „Ereignisname“ nicht erkennen und herausfiltern möchten, verwenden Sie das Filtersymbol rechts, um nur die anzuzeigenden Ereignisse auszuwählen.
PerfView
PerfView ist ein vom .NET-Team erstelltes Leistungstool, das ETW-Ablaufverfolgungen auflisten und anzeigen kann. Es kann auch Ablaufverfolgungsdateien anzeigen, die von anderen Tools in verschiedenen Formaten aufgelistet werden. In diesem Tutorial listen Sie eine ETW-Ablaufverfolgung der Demo-App auf und untersuchen dann die aufgelisteten Ereignisse in der PerfView-Ereignisanzeige.
Erfassen einer Ablaufverfolgung
Laden Sie PerfView von der Releaseseite herunter. Dieses Tutorial wurde mit PerfView-Version 2.0.76 erstellt, aber jede neuere Version sollte funktionieren.
Starten Sie PerfView.exe mit Administratorberechtigungen.
Hinweis
Die ETW-Ablaufverfolgungsauflistung erfordert immer Administratorberechtigungen. Wenn Sie PerfView jedoch nur zum Anzeigen einer bereits vorhandenen Ablaufverfolgung verwenden, sind keine speziellen Berechtigungen erforderlich.
Wählen Sie im Menü Auflisten die Option Ausführen aus. Dadurch wird ein neues Dialogfeld geöffnet, in dem Sie den Pfad zur Demo-App eingeben.
Um zu konfigurieren, welche Ereignisse aufgelistet werden, erweitern Sie erweiterten Optionen unten im Dialogfeld. Geben Sie im Textfeld Zusätzliche Anbieter unter Verwendung der oben beschriebenen Textkonventionen weitere Anbieter ein. In diesem Fall geben Sie „Demo:1:4“ ein, das bedeutet Schlüsselwortbit 1 (
Startup-Ereignisse) und Ausführlichkeitsebene 4 (Informational).
Um die App zu starten und mit der Auflistung der Ablaufverfolgung zu beginnen, wählen Sie die Schaltfläche Befehl ausführen aus. Wenn die App beendet wird, wird die Ablaufverfolgungsdatei PerfViewData.etl im aktuellen Verzeichnis gespeichert.
Anzeigen einer Ablaufverfolgung
Wählen Sie im Hauptfenster im Dropdown-Textfeld oben links das Verzeichnis aus, das die Ablaufverfolgungsdatei enthält. Doppelklicken Sie dann in der Strukturansicht darunter auf die Ablaufverfolgungsdatei.
Zum Öffnen der Ereignisanzeige doppelklicken Sie auf das Element Ereignisse, das in der Strukturansicht unterhalb der Ablaufverfolgungsdatei angezeigt wird.
Alle Ereignistypen in der Ablaufverfolgung werden in der Liste links angezeigt. Doppelklicken Sie auf einen Ereignistyp, z. B. „Demo\AppStarted“, um alle Ereignisse dieses Typs in der Tabelle auf der rechten Seite anzuzeigen.
Erfahren Sie mehr
Weitere Informationen zur Verwendung von PerfView finden Sie in den PerfView-Videotutorials.
dotnet-trace
dotnet-trace ist ein plattformübergreifendes Befehlszeilentool, das Ablaufverfolgungen von .NET Core-Apps mithilfe der EventPipe-Ablaufverfolgung auflisten kann. Das Anzeigen von Ablaufverfolgungsdaten wird nicht unterstützt, aber die aufgelisteten Ablaufverfolgungen können von anderen Tools wie PerfView oder Visual Studio angezeigt werden. dotnet-trace unterstützt auch das Konvertieren der Ablaufverfolgungen im .nettrace-Standardformat in andere Formate, z. B. Chromium oder Speedscope.
Erfassen einer Ablaufverfolgung
Laden Sie dotnet-trace herunter, und installieren Sie es.
Führen Sie an der Befehlszeile den Befehl dotnet-trace collect aus:
E:\temp\EventSourceDemo\bin\Debug\net6.0>dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exeDie Ausgabe sollte in etwa so aussehen:
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 verwendet die oben erläuterten Textkonventionen zur Beschreibung der Anbieterkonfiguration im Argument
--providers. Weitere Optionen zum Auflisten von Ablaufverfolgungen mithilfe von dotnet-trace finden Sie in der Dokumentation zu dotnet-trace.
EventListener
System.Diagnostics.Tracing.EventListener ist eine .NET-API, die prozessintern zum Empfangen von Rückrufen für Ereignisse verwendet werden kann, die von einer System.Diagnostics.Tracing.EventSource generiert werden. Diese API kann verwendet werden, um benutzerdefinierte Protokollierungstools zu erstellen oder die Ereignisse im Arbeitsspeicher zu analysieren, ohne sie jemals serialisieren zu müssen.
Um EventListener zu verwenden, deklarieren Sie einen Typ, der von EventListener abgeleitet wird, rufen Sie EnableEvents auf, um die Ereignisse aus einer beliebigen EventSource-Instanz von Interesse zu abonnieren, und überschreiben Sie die OnEventWritten-Methode, die aufgerufen wird, wenn ein neues Ereignis verfügbar ist. Es ist häufig hilfreich, OnEventSourceCreated zu überschreiben, um zu ermitteln, welche EventSource-Objekte vorhanden sind, aber es ist nicht erforderlich. Im Folgenden sehen Sie ein Beispielimplementierung von EventListener, die beim Empfang von Nachrichten eine Meldung in der Konsole ausgibt:
Fügen Sie diesen Code zur Demo-App hinzu.
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); } }Ändern Sie die
Main-Methode, um eine Instanz des neuen Listeners zu erstellen.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); }Erstellen Sie die App, und führen Sie sie aus. Zuvor hatte die Methode keine Ausgabe, aber jetzt schreibt sie die Ereignisse in die Konsole:
3/24/2022 9:23:35 AM AppStarted 3/24/2022 9:23:35 AM RequestStart 3/24/2022 9:23:35 AM RequestStop
