EVENT_DESCRIPTOR structure (evntprov.h)

Article
08/23/2023

La structure EVENT_DESCRIPTOR contient des informations (métadonnées) sur un événement ETW.

Syntaxe

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

Membres

Id

Nombre 16 bits utilisé pour identifier les événements basés sur le manifeste.

Pour l’ETW basé sur un manifeste, la combinaison Provider.DecodeGuid + Event.Id + Event.Version doit identifier un événement de manière unique, c’est-à-dire que tous les événements avec le même DecodeGuid, Id et Version doivent avoir le même ensemble de champs sans modification des noms de champs, des types de champs ou de l’ordre des champs.

Pour l’ETW sans manifeste (c’est-à-dire TraceLogging), le champ Id n’est généralement pas significatif et est normalement défini sur 0. Les événements TraceLogging sont généralement identifiés par leur nom d’événement, et non par l’ID d’événement.

Version

Nombre 8 bits utilisé pour spécifier la version d’un événement basé sur un manifeste.

La version indique une révision de la définition d’un événement avec un ID particulier. Tous les événements avec un ID donné doivent avoir une sémantique similaire, mais un changement de version peut être utilisé pour indiquer une modification mineure des détails de l’événement, par exemple une modification du type d’un champ ou l’ajout d’un nouveau champ.

Channel

Nombre 8 bits utilisé pour activer le traitement d’événements spéciaux.

Les événements basés sur un manifeste utilisent normalement le canal 0.
Les événements basés sur TraceLogging utilisent normalement le canal 11.
Les événements basés sur un manifeste avec des caractéristiques de fournisseur utilisent normalement le canal 12.
D’autres valeurs de canal peuvent être utilisées avec les événements du journal des événements.

Les valeurs de canal inférieures à 16 sont réservées à Microsoft pour permettre un traitement spécial par le runtime ETW. Les valeurs de canal 16 et ultérieures sont ignorées par le runtime ETW (traités de la même façon que le canal 0) et peuvent recevoir une sémantique définie par l’utilisateur.

Level

Nombre 8 bits utilisé pour décrire la gravité ou l’importance d’un événement.

Important

Le niveau d’événement est un moyen principal de filtrer les événements. Affectez toujours un niveau significatif (autre que zéro) à chaque événement.

Les valeurs de niveau 0 à 5 sont définies par Microsoft (voir evntrace.h et winmeta.h). Les valeurs de niveau 6 à 15 sont réservées. Les valeurs de niveau 16 à 255 peuvent être définies par le fournisseur d’événements.

Valeur	Sémantique
LOG_ALWAYS (0)	L’événement contourne le filtrage d’événements basé sur le niveau. Les événements ne doivent pas utiliser ce niveau.
CRITIQUE (1)	Erreur critique
ERREUR (2)	Erreur
AVERTISSEMENT (3)	Avertissement
INFO (4)	Informationnel
VERBOSE (5)	Commentaires

Les sessions de collection d’événements peuvent définir un filtre de niveau, ce qui signifie que la session n’accepte que les événements où eventDescriptor.Level <= session.LevelFilter. Notez que les événements avec un niveau de 0 ignorent le filtrage basé sur le niveau.

Opcode

Nombre 8 bits utilisé pour marquer des événements avec une sémantique spéciale. Cette valeur peut être utilisée par les décodeurs de trace pour organiser et mettre en corrélation des événements. Les valeurs opcode reconnues à l’échelle mondiale sont définies dans winmeta.h. La plupart des événements utilisent INFO (0). La sémantique définie par l’utilisateur peut être donnée aux valeurs opcode comprises entre 10 et 239.

Les opcodes START (1) et STOP (2) sont utilisés pour indiquer le début et la fin des activités ETW comme suit :

Générez un ID d’activité unique dans la trace, généralement à l’aide d’EventActivityIdControl.
Écrivez un événement de démarrage avec opcode = START, ID d’activité = l’ID d’activité généré et l’ID d’activité associé = l’ID d’activité parent (le cas échéant).
Écrivez un nombre quelconque d’événements d’informations d’activité avec opcode = INFO, ID d’activité = l’ID d’activité généré.
Écrivez un événement d’arrêt avec opcode = STOP, ID d’activité = l’ID d’activité généré.

Les outils de décodage de trace peuvent ensuite organiser ces événements en groupes en fonction de leurs ID d’activité.

Task

Nombre 16 bits utilisé pour annoter un événement ou un groupe d’événements associé.

Le code de tâche d’événement peut être utilisé à n’importe quelle fin définie par le fournisseur. Le code de tâche 0 est la valeur par défaut, utilisée pour indiquer qu’aucun code de tâche spécial n’a été affecté à l’événement. Le manifeste ETW prend en charge l’affectation de chaînes localisées à chaque code de tâche. Le code de tâche peut être utilisé pour regrouper des événements en catégories ou pour simplement associer une chaîne « tâche » localisée à chaque événement.

Keyword

Masque de bits 64 bits utilisé pour indiquer l’appartenance d’un événement à un ensemble de catégories d’événements.

Important

La mot clé d’événements est un moyen principal de filtrer les événements. Affectez toujours une mot clé significative (non nulle) à chaque événement.

Les 16 premiers bits du mot clé (masque de bits 0xFFFF000000000000) sont définis par Microsoft. Les 48 bits faibles du mot clé (masque de bits 0x0000FFFFFFFFFFFF) sont définis par le fournisseur d’événements. Par exemple, le fournisseur d’événements peut définir bit 0 (masque de bits 0x1) comme étant la catégorie « E/S », bit 1 (masque de bits 0x2) comme catégorie « Interface utilisateur » et bit 2 (masque de bits 0x4) comme catégorie « Mesure des performances ». Dans ce scénario, son mot clé peut être défini sur 0x5, ce qui indique que l’événement se trouve dans les catégories « E/S » et « Mesure des performances ».

Les sessions de collection d’événements peuvent définir les filtres MatchAnyKeyword et MatchAllKeyword, ce qui signifie que la session n’accepte que les événements pour lesquels l’expression suivante est vraie :

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

Notez que les événements avec une mot clé de 0 contournent normalement le filtrage basé sur mot clé.

Conseil

À compter de Windows 10 version 1507 et ultérieure, une session de collecte d’événements peut exclure les événements dont le mot clé est défini sur 0. Pour ce faire, incluez l’indicateur EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 dans le EnableProperty champ de la structure ENABLE_TRACE_PARAMETERS qui est passée à EnableTraceEx2 lors de la configuration du fournisseur.

Remarques

Cette structure est utilisée lors de l’appel d’EventWrite pour écrire l’événement. Vous pouvez également l’utiliser lors de l’appel d’EventEnabled pour déterminer si l’événement doit être généré (c’est-à-dire pour déterminer si des écouteurs d’événements sont intéressés par l’événement).

Notes

La plupart des fournisseurs d’événements n’utilisent pas EVENT_DESCRIPTOR directement. Au lieu de cela, la plupart des fournisseurs d’événements sont implémentés à l’aide d’une infrastructure ETW qui encapsule les appels à EventRegister, EventWriteEx et EventUnregister. Par exemple, vous pouvez écrire un manifeste d’événement , puis utiliser le compilateur de messages pour générer du code C/C++ pour les événements, ou vous pouvez utiliser TraceLogging pour éviter d’avoir besoin d’un manifeste. Pour plus d’informations sur la façon dont les membres de cette structure sont liés au manifeste d’instrumentation, consultez les attributs du type complexe EventDefinitionType .

Cette structure est incluse dans la structure EVENT_HEADER qui est retournée avec l’enregistrement d’événement lorsque vous consommez des événements à l’aide de ProcessTrace avec le rappel EventRecordCallback .

Notes

Lors du traitement d’événements basés sur MOF, l’identité d’événement est contenue dans le champ Opcode , et non dans le champ Id .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
En-tête	evntprov.h (inclure Evntprov.h)