EVENT_DESCRIPTOR-Struktur (evntprov.h)

Artikel
08/23/2023

Die EVENT_DESCRIPTOR-Struktur enthält Informationen (Metadaten) zu einem ETW-Ereignis.

Syntax

typedef struct _EVENT_DESCRIPTOR {
  USHORT    Id;
  UCHAR     Version;
  UCHAR     Channel;
  UCHAR     Level;
  UCHAR     Opcode;
  USHORT    Task;
  ULONGLONG Keyword;
} EVENT_DESCRIPTOR, *PEVENT_DESCRIPTOR;

Member

Id

Eine 16-Bit-Zahl, die zum Identifizieren manifestbasierter Ereignisse verwendet wird.

Für manifestbasierte ETW sollte die Kombination Provider.DecodeGuid + Event.Id + Event.Version ein Ereignis eindeutig identifizieren, d. h. alle Ereignisse mit der gleichen DecodeGuid, Id und Version sollten denselben Satz von Feldern ohne Änderungen an Feldnamen, Feldtypen oder Feldreihenfolge aufweisen.

Für manifestfreie ETW (d. h. TraceLogging) ist das Feld Id in der Regel nicht aussagekräftig und wird normalerweise auf 0 festgelegt. TraceLogging-Ereignisse werden in der Regel durch ihren Ereignisnamen und nicht durch die Ereignis-ID identifiziert.

Version

Eine 8-Bit-Zahl, die verwendet wird, um die Version eines manifestbasierten Ereignisses anzugeben.

Die Version gibt eine Revision der Definition eines Ereignisses mit einer bestimmten ID an. Alle Ereignisse mit einer bestimmten ID sollten eine ähnliche Semantik aufweisen, aber eine Versionsänderung kann verwendet werden, um eine geringfügige Änderung der Ereignisdetails anzuzeigen, z. B. eine Änderung des Feldtyps oder das Hinzufügen eines neuen Felds.

Channel

Eine 8-Bit-Zahl, die verwendet wird, um spezielle Ereignisverarbeitung zu ermöglichen.

Manifestbasierte Ereignisse verwenden normalerweise Kanal 0.
TraceLogging-basierte Ereignisse verwenden normalerweise Kanal 11.
Manifestbasierte Ereignisse mit Anbietermerkmalen verwenden normalerweise Kanal 12.
Andere Kanalwerte können mit Ereignisprotokollereignissen verwendet werden.

Kanalwerte unter 16 sind für die Verwendung durch Microsoft reserviert, um eine spezielle Behandlung durch die ETW-Runtime zu ermöglichen. Kanalwerte 16 und höher werden von der ETW-Runtime ignoriert (behandelt wie Kanal 0) und können benutzerdefinierte Semantik erhalten.

Level

Eine 8-Bit-Zahl, die verwendet wird, um den Schweregrad oder die Wichtigkeit eines Ereignisses zu beschreiben.

Wichtig

Die Ereignisebene ist ein primäres Mittel zum Filtern von Ereignissen. Weisen Sie jedem Ereignis immer eine sinnvolle Ebene (ungleich 0) zu.

Die Werte der Ebenen 0 bis 5 werden von Microsoft definiert (siehe evntrace.h und winmeta.h). Die Werte der Ebenen 6 bis 15 sind reserviert. Die Werte der Ebenen 16 bis 255 können vom Ereignisanbieter definiert werden.

Wert	Semantik
LOG_ALWAYS (0)	Das Ereignis umgeht die ebenenbasierte Ereignisfilterung. Ereignisse sollten diese Ebene nicht verwenden.
KRITISCH (1)	Schwerwiegender Fehler
FEHLER (2)	Fehler
WARNUNG (3)	Warnung
INFO (4)	Informational
VERBOSE (5)	Ausführlich

Ereignissammlungssitzungen können einen Ebenenfilter festlegen, was bedeutet, dass die Sitzung nur Ereignisse akzeptiert, bei denen eventDescriptor.Level <= session.LevelFilter. Beachten Sie, dass Ereignisse mit der Ebene 0 die ebenenbasierte Filterung umgehen.

Opcode

Eine 8-Bit-Zahl, die verwendet wird, um Ereignisse mit einer speziellen Semantik zu markieren. Dieser Wert kann von Ablaufverfolgungsdecodern verwendet werden, um Ereignisse zu organisieren und zu korrelieren. Global erkannte Opcodewerte werden in winmeta.h definiert. Die meisten Ereignisse verwenden INFO (0). Die Opcodewerte 10 bis 239 können benutzerdefinierte Semantiken erhalten.

Die Opcodes START (1) und STOP (2) werden verwendet, um den Anfang und das Ende der ETW-Aktivitäten wie folgt anzugeben:

Generieren Sie eine Aktivitäts-ID, die innerhalb der Ablaufverfolgung eindeutig ist, in der Regel mithilfe von EventActivityIdControl.
Schreiben Sie ein Startereignis mit opcode = START, Aktivitäts-ID = die generierte Aktivitäts-ID und die zugehörige Aktivitäts-ID = die übergeordnete Aktivitäts-ID (falls vorhanden).
Schreiben Sie eine beliebige Anzahl von Aktivitätsinformationsereignissen mit opcode = INFO, Aktivitäts-ID = die generierte Aktivitäts-ID.
Schreiben Sie ein Stoppereignis mit opcode = STOP, Aktivitäts-ID = die generierte Aktivitäts-ID.

Ablaufverfolgungsdecodierungstools können diese Ereignisse dann basierend auf ihren Aktivitäts-IDs in Gruppen organisieren.

Task

Eine 16-Bit-Zahl, die zum Kommentieren eines Ereignisses oder einer zugehörigen Gruppe von Ereignissen verwendet wird.

Der Ereignistaskcode kann für jeden vom Anbieter definierten Zweck verwendet werden. Der Taskcode 0 ist die Standardeinstellung, mit der angegeben wird, dass dem Ereignis kein spezieller Aufgabencode zugewiesen wurde. Das ETW-Manifest unterstützt das Zuweisen lokalisierter Zeichenfolgen zu jedem Aufgabencode. Der Aufgabencode kann verwendet werden, um Ereignisse in Kategorien zu gruppieren oder jedem Ereignis einfach eine lokalisierte "Task"-Zeichenfolge zuzuordnen.

Keyword

Eine 64-Bit-Bitmaske, die verwendet wird, um die Mitgliedschaft eines Ereignisses in einer Reihe von Ereigniskategorien anzugeben.

Wichtig

Ereignis Schlüsselwort (keyword) ist ein primäres Mittel zum Filtern von Ereignissen. Weisen Sie jedem Ereignis immer einen aussagekräftigen (ungleich 0) Schlüsselwort (keyword) zu.

Die obersten 16 Bits der Schlüsselwort (keyword) (Bitmaske 0xFFFF000000000000) werden von Microsoft definiert. Die niedrigen 48 Bits der Schlüsselwort (keyword) (Bitmaske 0x0000FFFFFFFFFFFF) werden vom Ereignisanbieter definiert. Der Ereignisanbieter kann beispielsweise Bit 0 (Bitmaske 0x1) als E/A-Kategorie, Bit 1 (Bitmaske 0x2) als Kategorie "UI" und Bit 2 (Bitmaske 0x4) als Kategorie "Leistungsmessung" definieren. In diesem Szenario kann die Schlüsselwort (keyword) für ein Ereignis auf 0x5 festgelegt sein, was angibt, dass das Ereignis sowohl in den Kategorien "E/A" als auch "Leistungsmessung" enthalten ist.

Ereignissammlungssitzungen können MatchAnyKeyword- und MatchAllKeyword-Filter festlegen, was bedeutet, dass die Sitzung nur Ereignisse akzeptiert, bei denen der folgende Ausdruck true ist:

eventDescriptor.Keyword == 0 || (
    (eventDescriptor.Keyword & session.MatchAnyKeyword) != 0 &&
    (eventDescriptor.Keyword & session.MatchAllKeyword) == session.MatchAllKeyword
)

Beachten Sie, dass Ereignisse mit dem Schlüsselwort (keyword) 0 normalerweise Schlüsselwort (keyword)-basierte Filterung umgehen.

Tipp

Ab Windows 10 Version 1507 und höher kann eine Ereignissammlungssitzung Ereignisse ausschließen, deren Schlüsselwort (keyword) auf 0 festgelegt ist. Fügen Sie dazu das EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 Flag in das EnableProperty Feld der ENABLE_TRACE_PARAMETERS-Struktur ein, das beim Konfigurieren des Anbieters an EnableTraceEx2 übergeben wird.

Hinweise

Diese Struktur wird verwendet, wenn EventWrite aufgerufen wird, um das Ereignis zu schreiben. Sie können es auch beim Aufrufen von EventEnabled verwenden, um zu bestimmen, ob das Ereignis generiert werden soll (d. h. um zu bestimmen, ob Ereignislistener an dem Ereignis interessiert sind).

Hinweis

Die meisten Ereignisanbieter verwenden EVENT_DESCRIPTOR nicht direkt. Stattdessen werden die meisten Ereignisanbieter mithilfe eines ETW-Frameworks implementiert, das die Aufrufe von EventRegister, EventWriteEx und EventUnregister umschließt. Sie können beispielsweise ein Ereignismanifest schreiben und dann den Nachrichtencompiler verwenden, um C/C++-Code für die Ereignisse zu generieren, oder Sie können TraceLogging verwenden, um die Notwendigkeit eines Manifests zu vermeiden. Ausführliche Informationen zur Beziehung der Member dieser Struktur zum Instrumentierungsmanifest finden Sie unter den Attributen des komplexen Typs EventDefinitionType .

Diese Struktur ist in der EVENT_HEADER-Struktur enthalten, die mit dem Ereignisdatensatz zurückgegeben wird, wenn Sie Ereignisse mithilfe von ProcessTrace mit dem EventRecordCallback-Rückruf nutzen.

Hinweis

Bei der Verarbeitung von MOF-basierten Ereignissen ist die Ereignisidentität im Opcode-Feld enthalten, nicht im Id-Feld .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Kopfzeile	evntprov.h (include Evntprov.h)