Erste Schritte mit EventSource

Dieser Artikel gilt für: ✔️ .NET Core 3.1 und höhere Versionen ✔️ .NET Framework 4.5 und höhere Versionen

In dieser exemplarischen Vorgehensweise wird gezeigt, wie Sie ein neues Ereignis mit System.Diagnostics.Tracing.EventSource protokollieren, Ereignisse in einer Ablaufverfolgungsdatei sammeln, die Ablaufverfolgung anzeigen und grundlegende EventSource-Konzepte verstehen.

Protokollieren eines Ereignisses

Das Ziel von EventSource ist es, .NET-Entwicklern zu ermöglichen, Code wie diesen zu schreiben, um ein Ereignis zu protokollieren:

DemoEventSource.Log.AppStarted("Hello World!", 12);

Diese Codezeile enthält ein Protokollierungsobjekt (DemoEventSource.Log), eine Methode, die das zu protokollierende Ereignis darstellt (AppStarted) und optional einige stark typisierte Ereignisparameter (HelloWorld! und 12). Es gibt keine Ausführlichkeitsgrade, Ereignis-IDs, Nachrichtenvorlagen oder irgendetwas anderes, das nicht an der Aufrufsite vorhanden sein muss. All diese anderen Informationen über Ereignisse werden durch die Definition einer neuen, von System.Diagnostics.Tracing.EventSource abgeleiteten Klasse geschrieben.

Hier ist ein vollständiges Minimalbeispiel:

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);
    }
}

Die DemoEventSource-Klasse deklariert eine Methode für jede Art von Ereignis, das Sie protokollieren möchten. In diesem Fall wird ein einzelnes Ereignis namens „AppStarted“ durch die Methode „AppStarted()“ definiert. Jedes Mal, wenn der Code die AppStarted-Methode aufruft, wird ein weiteres AppStarted-Ereignis in der Ablaufverfolgung aufgezeichnet, wenn das Ereignis aktiviert ist. Dies sind einige der Daten, die bei jedem Ereignis erfasst werden können:

• Ereignisname – Ein Name, der die Art des protokollierten Ereignisses identifiziert. Der Ereignisname ist identisch mit dem Namen der Methode, in diesem Fall „AppStarted“.
• Ereignis-ID – Eine numerische ID, die die Art des protokollierten Ereignisses identifiziert. Dies hat eine ähnliche Funktion wie der Name, kann aber bei der schnellen automatischen Protokollverarbeitung helfen. Das AppStarted-Ereignis hat eine ID von 1, die in EventAttribute angegeben ist.
• Quellname – Der Name der EventSource, die das Ereignis enthält. Dieser wird als Namespace für Ereignisse verwendet. Ereignisnamen und IDs müssen nur innerhalb des Bereichs ihrer Quelle eindeutig sein. Hier heißt die Quelle „Demo“, angegeben in EventSourceAttribute bei der Klassendefinition. Der Quellname wird im Allgemeinen auch als Anbietername bezeichnet.
• Argumente – Alle Methodenargumentwerte werden serialisiert.
• Sonstige Informationen – Ereignisse können auch Zeitstempel, Thread-IDs, Prozessor-IDs, Aktivitäts-IDs, Ablaufverfolgungen und Ereignismetadaten wie Nachrichtenvorlagen, Ausführlichkeitsgrade und Schlüsselwörter enthalten.

Weitere Informationen und bewährte Methoden zum Erstellen von Ereignissen finden Sie unter Instrumentierungscode zum Erstellen von Ereignissen.

Sammeln und Anzeigen einer Ablaufverfolgungsdatei

Es ist keine Konfiguration im Code erforderlich, die beschreibt, welche Ereignisse aktiviert werden sollen, wohin die protokollierten Daten gesendet werden sollen oder in welchem Format die Daten gespeichert werden sollen. Wenn Sie die App jetzt ausführen, wird sie standardmäßig keine Ablaufverfolgungsdatei erzeugen. EventSource verwendet das Veröffentlichen/Abonnieren-Muster, bei dem Abonnenten die Ereignisse angeben müssen, die aktiviert werden sollen, und die gesamte Serialisierung für die abonnierten Ereignisse steuern. EventSource verfügt über Integrationen für das Abonnieren über Ereignisablaufverfolgung für Windows (Event Tracing for Windows, ETW) und EventPipe (nur .NET Core). Benutzerdefinierte Abonnenten können auch mithilfe der System.Diagnostics.Tracing.EventListener-API erstellt werden.

Diese Demo zeigt ein EventPipe-Beispiel für .NET Core-Apps. Weitere Informationen zu weiteren Optionen finden Sie unter Sammeln und Anzeigen von Ereignisablaufverfolgungen. EventPipe ist eine offene und plattformübergreifende Ablaufverfolgungstechnologie, die in die .NET Core Runtime integriert ist, um .NET-Entwicklern Tools zur Ablaufverfolgung und ein portables kompaktes Ablaufverfolgungsformat (*.nettrace-Dateien) zur Verfügung zu stellen. dotnet-trace ist ein Befehlszeilentool, das EventPipe-Ablaufverfolgungen sammelt.

1. Laden Sie dotnet-trace herunter, und installieren Sie es.
2. Erstellen Sie die obige Konsolen-App. Bei dieser Demo wird davon ausgegangen, dass die App den Namen „EventSourceDemo.exe“ aufweist und sich im aktuellen Verzeichnis befindet. Führen Sie Folgendes über die Befehlszeile aus:

>dotnet-trace collect --providers Demo -- EventSourceDemo.exe

Die Ausgabe sollte in etwa so aussehen:

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.

Dieser Befehl führt „EventSourceDemo.exe“ mit allen Ereignissen in der EventSource „Demo“ aus und gibt die Ablaufverfolgungsdatei EventSourceDemo.exe_20220303_001619.nettrace aus. Wenn Sie die Datei in Visual Studio öffnen, werden die protokollierten Ereignisse angezeigt.

In der Listenansicht können Sie sehen, dass das erste Ereignis das Ereignis „Demo/AppStarted“ ist. Die Textspalte enthält die gespeicherten Argumente, die Zeitstempelspalte zeigt, dass das Ereignis 27 ms nach Beginn der Protokollierung eingetreten ist, und rechts daneben sehen Sie die Aufrufliste. Die anderen Ereignisse werden automatisch in jeder Ablaufverfolgung von dotnet-trace aktiviert. Sie können jedoch ignoriert und aus der Anzeige auf der Benutzeroberfläche gefiltert werden, wenn sie stören. Diese zusätzlichen Ereignisse erfassen einige Informationen über den Prozess und den mit JIT-kompilierten Code, die es Visual Studio ermöglichen, die Ablaufverfolgungen für den Ereignisstapel zu rekonstruieren.

Weitere Informationen zu EventSource

• Instrumentierungscode zum Erstellen von Ereignissen
• Sammeln und Anzeigen von Ereignisablaufverfolgungen