Freigeben über

Instrumentieren Ihres Codes mit ETW

Event Tracing for Windows (ETW) ist eine in Windows integrierte Hochgeschwindigkeitsablaufverfolgungsfunktion. Mithilfe eines im Betriebssystemkernel implementierten Pufferungs- und Protokollierungsmechanismus bietet ETW eine Infrastruktur für Ereignisse, die sowohl von Benutzermodus- (Apps) als auch von Kernelmoduskomponenten (Treibern) ausgelöst werden. ETW kann für System- und App-Diagnose, Fehlerbehebung und Leistungsüberwachung verwendet werden.

In der Vergangenheit wurde die Ablaufverfolgung verwendet, um unerwartetes Verhalten sowohl in Hardware als auch in Apps zu diagnostizieren. In letzter Zeit gibt es jedoch eine steigende Nachfrage nach Verwaltung und Überwachung der Systemstabilität und -leistung, um Geschäftsanforderungen zu erfüllen. Infolgedessen ist die Leistungsanalyse in Entwicklungs- und Produktionsumgebungen zu einem wichtigen Bestandteil der Computerwelt geworden. Im Gegensatz zu Ausfällen und Fehlern sind leistungsbezogene Probleme schwer zu erkennen und zu diagnostizieren, da sie häufig von Konfiguration und Arbeitslast abhängen. Die Ablaufverfolgung in einer Produktionsumgebung liefert wertvolle Daten zur Erkennung von leistungsbezogenen Problemen an der Grundursache sowie zur Kapazitätsplanung und -bewertung.

Mit dem ETW-Mechanismus können Sie Ablaufverfolgungssitzungen dynamisch steuern, wodurch eine detaillierte Ablaufverfolgung in Produktionsumgebungen ohne Systemneustart oder App-Neustart erfasst werden kann.

Der folgende Abschnitt zeigt, wie Sie ETW verwenden, um eine präzise Leistungsmessung und -analyse durchzuführen:

  • Kernelmodus-Treibercode
  • Herkömmliche Desktop-Prozesse und -Dienste
  • Microsoft Store-Apps (C#)

Übersicht

Die folgende Liste zeigt einige der vorteilhaften Eigenschaften von ETW:

Robust

Es bietet effiziente Pufferungs- und Protokollierungsmechanismen. Der Ablaufverfolgungspuffer wird vom Kernel verwaltet. Die Ablaufverfolgung über ETW ist immun gegen App-Abstürze und -Aufhänger. Im Falle eines Systemausfalls sind nicht gespeicherte Ereignisse in einer Speicherauszugsdatei zugänglich.

Dynamisch

Ablaufverfolgungssitzungen können ohne Systemneustart oder App-Neustarts dynamisch gestartet, gestoppt, neu konfiguriert und angehalten werden. ETW bietet mehrere Modi, um verschiedene Anforderungen zu erfüllen.

In Windows integriert

Außer der Controller-App benötigen Sie keine zusätzlichen Tools. Windows verfügt über einige Posteingangscontroller sowie Consumer-Apps.

Einfache

Da der Overhead der Verlaufsverfolgung und der gespeicherten Protokolldateien hochoptimiert ist, wirken sie sich nicht auf die App- oder Systemleistung aus. Der Protokollierungsmechanismus verwendet Puffer im Kernelmodus, die von einem separaten Writer-Thread auf die Festplatte geschrieben werden, sodass der Aufwand für die Ablaufverfolgung begrenzt ist.

Vor Windows 2000 waren in Windows nur grundlegende textbasierte Ablaufverfolgungsmechanismen verfügbar: DbgPrint() und DebugPrint()-APIs. Sie erforderten Debugger und waren in der Regel nicht dynamisch steuerbar. Der Ablaufverfolgungsmechanismus von Windows hat sich im Laufe der Zeit weiterentwickelt; Heute stehen vier verschiedene Verfolgungsmechanismen zur Verfügung. ETW- und Ereignisprotokoll-API-Sätze wurden mit dem einheitlichen Ereignisprotokollierungs-API-Satz in Windows Vista zusammengeführt, der Benutzern und Entwicklern einen einheitlichen Mechanismus zum Auslösen von Ereignissen bietet.

Es gibt drei Arten von Ereignissen:

  1. Windows Software Trace Preprocessor (WPP) und klassisches ETW

  2. Managed Object Format (MOF): Das MOF ist eine Möglichkeit, WMI-Objekte zu beschreiben und Ereignisse zu aktivieren und zu decodieren.

  3. Manifestbasiert: In Windows Vista wurde eine XML-basierte einheitliche Ablaufverfolgungsdefinition eingeführt. Eine XML-Datei enthält Elemente für Ereignisse, die ein Anbieter schreibt. Weitere Informationen finden Sie unter Schreiben eines Instrumentierungsmanifests.

Hinweis

Die Anleitung in diesem Abschnitt konzentriert sich ausschließlich auf die Manifest-basierte Ereignisinstrumentierung.

ETW hat die folgenden wichtigen Eigenschaften:

  • Entwickler können die richtigen Implementierungssätze basierend auf der beabsichtigten Verwendung auswählen (z. B. kann Printf, wie die WPP-Implementierung, einfach für Debugging-Zweck-Ereignisse hinzugefügt werden).

  • Die Infrastruktur verwaltet häufig verwendete Informationen wie Zeitstempel, Funktionsnamen und Zeilennummern der Quelldatei.

  • Dieselbe Implementierung wird für Benutzermodus-Apps und Kernelmodus-Komponenten verwendet.

  • Auf ETW kann in Crash-Dumps und Live-Debug zugegriffen werden.

  • ETW kann für eine Echtzeitansicht an den Kernel-Debugger umgeleitet werden.

  • ETW hat eine Echtzeitansicht.

  • Protokolldateien werden in einer binären Protokolldatei (einer ETL-Datei) gespeichert.

  • ETW unterstützt die Protokollierung mehrerer Prozesse.

  • ETW hat einen hohen Durchsatz.

  • Protokolldateien können auf einem anderen Computer angezeigt werden.

  • ETW unterstützt die Umlaufpufferung für die kontinuierliche Protokollierung und Überwachung.

  • ETW kann basierend auf der Zielgruppe in einen der Kanäle gruppiert werden.

ETW-Architektur

Es gibt vier Hauptkomponenten in ETW: Anbieter, Sitzung, Controller und Verbraucher.

Diagramm der vier Hauptkomponenten der ETW-Architektur

Anbieter

Ein Anbieter ist eine instrumentierte Komponente, die Ereignisse generiert. Ein Anbieter kann eine App im Benutzermodus, ein Treiber im Kernelmodus oder der Windows-Kernel selbst sein. Zusätzlich zu festen Ereignisdaten (Header) kann ein Ereignis Benutzerdaten tragen.

Ein Ereignis ist eine ereignisbasierte Darstellung von Daten. Die Daten können für tiefergehende Analysen verwendet werden. Ein Ereignis kann auch verwendet werden, um Zähler zu erzeugen. Zähler bieten eine stichprobenbasierte Ansicht der Daten. Sie enthalten normalerweise einen kleinen Datensatz, um den aktuellen Status anzuzeigen, z. B. E/A-Bytes pro Sekunde und Interrupts pro Sekunde.

Ein Anbieter muss sich bei ETW registrieren und Ereignisse senden, indem er die ETW-Protokollierungs-APIs aufruft. Anbieter registrieren eine Callback-Funktion zum Aktivieren und Deaktivieren von Benachrichtigungen, sodass die Ablaufverfolgung dynamisch aktiviert und deaktiviert werden kann.

Sitzung

Die ETW-Sitzungsinfrastruktur fungiert als Zwischenbroker, der die Ereignisse von einem oder mehreren Anbietern an den Verbraucher weiterleitet. Eine Sitzung ist ein Kernel-Objekt, das Ereignisse im Kernel-Puffer sammelt und sie an eine bestimmte Datei oder einen Echtzeit-Verbraucherprozess sendet. Mehrere Anbieter können einer einzigen Sitzung zugeordnet werden, wodurch Benutzer Daten aus mehreren Quellen sammeln können.

Controller

Ein Controller startet, stoppt oder aktualisiert eine Ablaufverfolgungssitzung. Eine Sitzung ist eine Einheit für die Ablaufverfolgung. Anbieter werden einer bestimmten Sitzung zugeordnet (oder aktiviert). Ein Controller aktiviert und deaktiviert Anbieter, damit sie mit dem Senden von Ereignissen an ETW beginnen können. Controller-Funktionalitäten können mit Tools aufgerufen werden, die von Microsoft bereitgestellt werden, oder Sie können Ihre eigene App schreiben.

Logman.exe ist eine integrierte Controller-App. Windows Performance Recorder (WPR) im Windows Performance Toolkit ist der empfohlene Controller-Prozess.

Consumer

Ein Verbraucher ist eine App, die eine protokollierte Ablaufverfolgungsdatei (ETL-Datei) liest oder Ereignisse in einer aktiven Ablaufverfolgungssitzung in Echtzeit erfasst und Ereignisse verarbeitet. Ereignisanzeige und Ressourcenmonitor sind integrierte ETW-Verbraucher-Apps.

Windows Leistungsanalyse (WPA) im Windows Performance Toolkit ist der empfohlene Verbraucherprozess.

Implementieren der ETW-Instrumentierung

Planen Sie Ihre Instrumentierung

Entscheiden Sie, wo ETW-Ereignisse in Ihrem Code protokolliert werden sollen. Diese Protokollierung sollte mit wichtigen Benutzerszenarien oder häufigen Anwendungsfällen korrelieren, die Sie messen, analysieren und schließlich verbessern möchten. Die folgende Liste zeigt einige Beispiele dafür, was instrumentiert werden könnte:

  • Statusänderungen
  • Beginn/Ende wesentlicher Vorgänge
  • Ressourcenerstellung/-löschung
  • Andere Ereignisse im Zusammenhang mit Leistung oder Zuverlässigkeit
  • Debug-Ereignisse

Erstellen Sie eine Manifestdatei und implementieren Sie Ihren Anbieter

Manifestbasierte ETW-Ereignisse können in Benutzermodus-Apps, einschließlich Diensten, und in Kernelmoduskomponenten wie Treibern implementiert werden, indem eine XML-Datei namens Ereignismanifest verwendet wird. Weitere Informationen finden Sie unter Ereignisablaufverfolgungsfunktionen.

Ein Ereignismanifest ist in die folgenden Abschnitte unterteilt:

Anbieterdefinition:< Anbieter >

Enthält den Namen und die GUID des Anbieters, den Sie erstellen, und den Speicherort der instrumentierten Binärdatei (die schließlich die vom ETW-Framework benötigten Instrumentierungsressourcen enthält).

Ereignisnutzlast: <Vorlagen>

Enthält Definitionen der Datentypen, die als Nutzdaten in die Ereignisse aufgenommen werden. Folgende Typen sind verfügbar:

  • 8-Bit-, 16-Bit-, 32-Bit- und 64-Bit-Ganzzahlen mit und ohne Vorzeichen

  • ANSI- und Unicode-Strings

  • Schweben und verdoppeln

  • Boolesch, Binär, GUID, Zeiger, FILETIME, SYSTEMTIME, SID und HexInt32

Statische Ereignisdaten
Wird verwendet, um die Ereignisse zu interpretieren, zu sortieren und zu gruppieren.
  • Definiert die Namen der Operationen (oder Aufgaben), die instrumentiert werden.
  • Definiert die Arten von Vorgängen, die Sie für Ihre Ereignisse erstellen möchten, z. B. das Startereignis, das Stoppereignis zum zeitlichen Begrenzen von Vorgängen, das Informationsereignis zum Protokollieren von Debugdaten usw.

  • Ereignisdefinition: <Ereignisse>

    Verknüpft Nutzlast und statische Daten. Ihr Code gibt Ereignisse gemäß der Definition in diesem Abschnitt aus.

Hier ist ein Beispiel für ein Ereignismanifest:

<provider
    guid="{3877cf22-0702-4dfc-965e-7fdc7780cd74}"
    name="MyEventProvider"
    symbol="MY_EVENT_PROVIDER"
    messageFileName="%temp%\MyProviderBinary.exe"
    resourceFileName="%temp%\MyProviderBinary.exe“
    >
  <templates>
    <template tid="T_MyProvider_1">
      <data inType="win:Int32" name="Operation Id" />
      <data inType="win:Int32" name="Memory Allocated (MB)" />
    </template>
  </templates>
  <opcodes>
    <opcode name="DebugInfo" symbol="_DebugInfo" value="10"/>  
  </opcodes>
  <tasks>
    <task name="OpMemAllocation" symbol="OpMemAllocation_Task" value="1“
          eventGUID="{87ebca33-bf25-442c-9256-82ba484586e8}"/>
  </tasks>
  <events>
    <event symbol="DebugInfo" template="T_MyProvider_1" value="200" 
       task="OpMemAllocation" opcode="DebugInfo" />
  </events>

Um Ihre Manifestdatei zu schreiben, können Sie Folgendes verwenden:

  • Manifest Generator (ECManGen.exe), verfügbar im Plattform-SDK

  • Visual Studio (Eventman.xsd), verfügbar im Platform SDK

Kompilieren Sie das Ereignismanifest

Der nächste Schritt besteht darin, das Manifest mithilfe des Message Compiler-Tools (mc.exe) zu kompilieren, das im Platform SDK verfügbar ist. Dieses Tool generiert einige Dateien, die zum Instrumentieren, Kompilieren und Erstellen Ihres instrumentierten Codes erforderlich sind:

ManifestFileName.h
Enthält Ereignisdeskriptoren zur Verwendung im Code.
ManifestFileName.rc
Ein Ressourcen-Compiler-Skript.
MSG00001.bin
Eine Sprachressource.
ManifestFileNameTEMP.bin
Eine Vorlagenressource (Anbieter und Metadaten).

Geben Sie Folgendes ein, um den Code für den Benutzermodus zu kompilieren:

     mc.exe -um [ManifestFileName]

Geben Sie Folgendes ein, um den Kernelmoduscode zu kompilieren:

     mc.exe -km [ManifestFileName]

Geben Sie Folgendes ein, um verwalteten oder JavaScript-Code zu kompilieren:

     mc.exe -cs [ManifestFileName]
     mc.exe -css [ManifestFileName]
     mc.exe -generateProjections [ManifestFileName]

Aktualisieren Ihres Codes

Im nächsten Schritt fügen Sie Ihrem Code Instrumentierung hinzu. Führen Sie Visual Studio aus, fügen Sie die vom Nachrichtencompiler generierte Headerdatei hinzu, und bauen Sie die Ressourcendatei in Ihr Programm ein.

Suchen Sie in der Kopfzeile nach Folgendem, um herauszufinden, welche Makros (oder Klassenmethoden) in Ihrem Code aufgerufen werden sollen:

  • EventRegister<YourProviderName>

    Wird verwendet, um Ihren Anbieter zu registrieren (beim App-Start).

  • EventUnregister<YourProviderName>

    Wird verwendet, um Ihren Anbieter zu registrieren (beim App-Start).

  • EventWrite

In Ihrem Manifest (im Ereignisknoten) ist für jedes Ereignis ein Makro (oder eine <Methode>) definiert.

Nachdem Ihr Code richtig instrumentiert wurde, können Sie Ihre Binärdatei erstellen.

Informationen zu Treibern finden Sie im EventDrv-Beispiel, das auf MSDN verfügbar ist. Registrieren Sie den Treiber als Ereignisanbieter, indem Sie die EtwRegister-Funktion des ETW-Kernelmodus verwenden:

  • Fügen Sie diese Funktion in Ihrer DriverEntry-Routine nach dem Code hinzu, der das Geräteobjekt erstellt und initialisiert.

  • Ordnen Sie den Aufruf der EtwRegister-Funktion einem Aufruf von EtwUnregister in der Unload-Routine Ihres Treibers zu.

Ereignisse protokollieren und visualisieren

Nachdem Sie über eine ordnungsgemäß instrumentierte Komponente verfügen, können Sie mit der Protokollierung von Ereignissen auf einem Testsystem beginnen. Sie müssen dieses System zunächst für die Protokollierung vorbereiten, indem Sie Ihren Anbieter mit wevtutil, dem Posteingangstool, registrieren.

  1. Kopieren Sie Ihre Komponente an den Speicherort, der in Ihrem Manifest durch das Attribut resourceFileName angegeben wurde:

    xcopy /y MyProviderBinary.exe %temp%

  2. Registrieren Sie die Anbieter:

    wevtutil um etwmanifest.man
    wetvutil im etwmanifest.man

  3. Stellen Sie sicher, dass der Anbieter sichtbar ist:

    Logman-Abfrageanbieter 

    Ihr Anbietername/GUID wird in der Liste angezeigt.

Beachten Sie, dass Ereignismetadaten in der instrumentierten Binärdatei und nicht in der Manifestdatei gespeichert werden. Die Verwendung von wevtutil zum Installieren eines Manifests auf dem PC fügt einen Link in die Registrierung ein, der die Anbieter-GUID mit der Binärdatei verbindet, die die Ereignismetadaten enthält. Name und Pfad dieser Binärdatei werden der bereitgestellten Manifestdatei entnommen. Sie können die Manifestdatei anschließend verwerfen.

Da es sich auf dem Computer befindet, den Sie zum Decodieren verwenden, muss auch die Binärdatei, die die Ereignismetadaten enthält, zugänglich und ladbar sein. WPR/xperf macht den Prozess portabler, indem die Metadaten in die Ablaufverfolgung eingefügt werden.

Nachdem Ihr Anbieter ordnungsgemäß auf diesem System installiert wurde, können Sie eine Ablaufverfolgungssitzung starten, um Ereignisse von Ihrer Komponente in einer ETL-Datei zu sammeln. Sie können entweder Windows Performance Recorder (WPR) oder Xperf, das Befehlszeilentool, verwenden, die beide im Windows Performance Toolkit verfügbar sind:

  1. Ablaufverfolgung starten:

    xperf -start MySession -on MyEventProvider -f MySession.etl

    In dieser Befehlszeile gibt -start der Ereigniserfassungssitzung einen Namen und -on teilt ETW mit, dass Sie in dieser Sitzung Ereignisse von Ihrem Anbieter erfassen möchten. (Es können mehrere -on-Argumente vorhanden sein.)

  2. Führen Sie Ihre Arbeitsbelastung aus.

  3. Ablaufverfolgung beenden:

    xperf -stop MySession

Nachdem Sie eine ETL-Datei haben, können Sie sie mit dem Windows Leistungsanalyse-Tool öffnen und Ihre Ereignisse mit dem Diagramm und der Tabelle für generische Ereignisse visualisieren.

Grafik und Diagramme generischer Ereignisse in Windows Performance Advisor (WPA)