Erste Schritte mit EventSource

Dieser Artikel bezieht sich auf: ✔️ .NET Core 3.1 und höhere Versionen ✔️ .NET Framework 4.5 und neuere Versionen

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

Hinweis

Viele Technologien, die mit EventSource integriert werden, verwenden den Begriff „Ablaufverfolgung“ anstelle von „Protokollierung“ und „Protokollen“. Die Bedeutung ist hier gleich.

Protokollieren eines Ereignisses

Das Ziel von EventSource besteht darin, .NET-Entwicklern das Schreiben von Code wie diesem zum Protokollieren eines Ereignisses zu ermöglichen:

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

Diese Codezeile verfügt über ein Protokollierungsobjekt (DemoEventSource.Log), eine Methode, die das zu protokollende Ereignis (AppStarted) darstellt, und optional einige stark typierte Ereignisparameter (HelloWorld! und 12). Es gibt keine Ausführlichkeitsgrade, Ereignis-IDs, Nachrichtenvorlagen oder irgendetwas anderes, das nicht an der Aufrufsite vorhanden sein muss. Alle weiteren Informationen zu Ereignissen werden definiert, indem eine neue Klasse erstellt wird, die von System.Diagnostics.Tracing.EventSource abgeleitet ist.

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 jeden Ereignistyp, den Sie protokollieren möchten. In diesem Fall wird ein einzelnes Ereignis namens "AppStarted" durch die AppStarted()-Methode definiert. Jedes Mal, wenn der Code die AppStarted-Methode aufruft, wird ein anderes AppStarted-Ereignis in der Ablaufverfolgung aufgezeichnet, wenn das Ereignis aktiviert ist. Dies sind einige der Daten, die mit jedem Ereignis erfasst werden können:

• Ereignisname – Ein Name, der die Art des protokollierten Ereignisses identifiziert. Der Ereignisname ist mit dem Methodennamen "AppStarted" in diesem Fall identisch.
• Ereignis-ID – Eine numerische ID, die die Art des protokollierten Ereignisses identifiziert. Dies dient einer ähnlichen Rolle wie der Name, kann aber bei der schnellen automatisierten Protokollverarbeitung helfen. Das AppStarted-Ereignis weist eine ID von 1 auf, die in der EventAttributeDatei angegeben ist.
• Quellname – Der Name der EventSource, die das Ereignis enthält. Dies 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", die in der EventSourceAttribute Klassendefinition angegeben ist. Der Quellname wird häufig auch als Anbietername bezeichnet.
• Argumente – Alle Methodenargumentwerte werden serialisiert.
• Andere Informationen – Ereignisse können auch Zeitstempel, Thread-IDs, Aktivitäts-IDs, Prozessor-IDs, Stapelverfolgungen und Ereignismetadaten wie Nachrichtenvorlagen, Ausführlichkeitsebenen 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 gibt keine erforderliche Konfiguration im Code, in der beschrieben wird, welche Ereignisse aktiviert werden sollen, wo die protokollierten Daten gesendet werden sollen oder in welchem Format die Daten gespeichert werden sollen. Wenn Sie die App jetzt ausführen, erzeugt sie von Haus aus keine Protokolldatei. EventSource verwendet das Veröffentlichungsabonnentmuster, bei dem Abonnenten die Ereignisse angeben müssen, die aktiviert werden sollen, und um die gesamte Serialisierung für die abonnierten Ereignisse zu 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-Entwickler-Ablaufverfolgungstools und ein portables kompaktes Ablaufverfolgungsformat (*.nettrace-Dateien) zu geben. dotnet-trace ist ein Befehlszeilentool, das EventPipe-Ablaufverfolgungen sammelt.

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

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

Dies sollte eine Ausgabe ähnlich der folgenden anzeigen:

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. Beim Öffnen der Datei in Visual Studio werden die protokollierten Ereignisse angezeigt.

In der Listenansicht können Sie sehen, dass das erste Ereignis das Demo-/AppStarted-Ereignis ist. Die Textspalte weist die gespeicherten Argumente auf, die Zeitstempelspalte zeigt das Ereignis 27 ms nach dem Start der Protokollierung und rechts sehen Sie den Aufrufstack. 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

• Instrumentieren von Code zum Erstellen von Ereignissen
• Sammeln und Anzeigen von Ereignisablaufverfolgungen