structure EVENT_TRACE_HEADER (evntrace.h)

La structure EVENT_TRACE_HEADER contient des informations de suivi d’événements standard communes à tous les événements écrits par TraceEvent.

Syntaxe

typedef struct _EVENT_TRACE_HEADER {
  USHORT        Size;
  union {
    USHORT FieldTypeFlags;
    struct {
      UCHAR HeaderType;
      UCHAR MarkerFlags;
    } DUMMYSTRUCTNAME;
  } DUMMYUNIONNAME;
  union {
    ULONG Version;
    struct {
      UCHAR  Type;
      UCHAR  Level;
      USHORT Version;
    } Class;
  } DUMMYUNIONNAME2;
  ULONG         ThreadId;
  ULONG         ProcessId;
  LARGE_INTEGER TimeStamp;
  union {
    GUID      Guid;
    ULONGLONG GuidPtr;
  } DUMMYUNIONNAME3;
  union {
    struct {
      ULONG KernelTime;
      ULONG UserTime;
    } DUMMYSTRUCTNAME;
    ULONG64 ProcessorTime;
    struct {
      ULONG ClientContext;
      ULONG Flags;
    } DUMMYSTRUCTNAME2;
  } DUMMYUNIONNAME4;
} EVENT_TRACE_HEADER, *PEVENT_TRACE_HEADER;

Membres

Size

Nombre total d’octets de l’événement. La taille inclut la taille de la structure d’en-tête, plus la taille de toutes les données spécifiques à l’événement ajoutées à l’en-tête.

En entrée, la taille doit être inférieure à la taille de la mémoire tampon de la session de suivi d’événements moins 72 (0x48).

En sortie, n’utilisez pas ce nombre dans les calculs.

DUMMYUNIONNAME

DUMMYUNIONNAME.FieldTypeFlags

Réservé.

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.HeaderType

Réservé.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.MarkerFlags

Réservé.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.Version

Il s’agit d’un cumul des membres de Class. L’octet de faible ordre contient le Type, l’octet suivant contient le Niveau et les deux derniers octets contiennent la version.

DUMMYUNIONNAME2.Class

DUMMYUNIONNAME2.Class.Type

Type d’événement. Un fournisseur peut définir ses propres types d’événements ou utiliser les types d’événements prédéfinis répertoriés dans le tableau suivant.

• EVENT_TRACE_TYPE_CHECKPOINT : événement Point de contrôle. Utilisez pour un événement qui n’est pas au début ou à la fin d’une activité.

• EVENT_TRACE_TYPE_DC_END : événement de fin de collecte de données.

• EVENT_TRACE_TYPE_DC_START : événement de démarrage de la collecte de données.

• EVENT_TRACE_TYPE_DEQUEUE : événement Dequeue. À utiliser lorsqu’une activité est mise en file d’attente avant de commencer. Utilisez EVENT_TRACE_TYPE_START pour marquer l’heure à laquelle un élément de travail est mis en file d’attente. Utilisez le type d’événement dequeue pour marquer l’heure à laquelle le travail sur l’élément commence réellement. Utilisez EVENT_TRACE_TYPE_END pour marquer l’heure à laquelle le travail sur l’élément se termine.

• EVENT_TRACE_TYPE_END : Événement de fin. Permet de suivre l’état final d’un événement en plusieurs étapes.

• EVENT_TRACE_TYPE_EXTENSION : événement d’extension. Utilisez pour un événement qui est une continuation d’un événement précédent. Par exemple, utilisez le type d’événement d’extension lorsqu’une trace d’événement enregistre plus de données que ne peut le faire une mémoire tampon de session.

• EVENT_TRACE_TYPE_INFO : événement informationnel. Il s’agit du type d’événement par défaut.

• EVENT_TRACE_TYPE_REPLY : événement répondre. À utiliser lorsqu’une application qui demande des ressources peut recevoir plusieurs réponses. Par exemple, si une application cliente demande une URL et que le serveur web répond en envoyant plusieurs fichiers, chaque fichier reçu peut être marqué comme événement de réponse.

• EVENT_TRACE_TYPE_START : événement Start. Permet de suivre l’état initial d’un événement en plusieurs étapes.

Si vous définissez vos propres types d’événements, vous devez utiliser des nombres commençant à partir de 10. Toutefois, rien ne vous empêche d’utiliser des nombres que vous souhaitez utiliser. Si votre GUID de classe de trace d’événements prend en charge plusieurs types d’événements, les consommateurs utiliseront le type d’événement pour déterminer l’événement et interpréter son contenu.

DUMMYUNIONNAME2.Class.Level

Valeur définie par le fournisseur qui définit le niveau de gravité utilisé pour générer l’événement. La valeur varie de 0 à 255. Le contrôleur spécifie le niveau de gravité lorsqu’il appelle la fonction EnableTraceEx2 . Le fournisseur récupère le niveau de gravité en appelant la fonction GetTraceEnableLevel à partir de son implémentation ControlCallback . Le fournisseur utilise la valeur pour définir ce membre.

ETW définit les niveaux de gravité suivants. La sélection d’un niveau supérieur à 1 inclut également les événements pour les niveaux inférieurs. Par exemple, si le contrôleur spécifie TRACE_LEVEL_WARNING (3), le fournisseur génère également des événements TRACE_LEVEL_FATAL (1) et TRACE_LEVEL_ERROR (2).

DUMMYUNIONNAME2.Class.Version

Indique la version de la classe de trace d’événements que vous utilisez pour journaliser l’événement. Spécifiez zéro s’il n’existe qu’une seule version de votre classe de trace d’événements. La version indique au consommateur la classe MOF à utiliser pour déchiffrer les données d’événement.

ThreadId

Lors de la sortie, identifie le thread qui a généré l’événement.

Notez que sur Windows 2000, ThreadId était une valeur ULONGLONG .

ProcessId

Lors de la sortie, identifie le processus qui a généré l’événement.

Windows 2000 : Ce membre n’est pas pris en charge.

TimeStamp

Sur la sortie, contient l’heure à laquelle l’événement s’est produit. La résolution est l’heure système, sauf si le membre ProcessTraceMode de EVENT_TRACE_LOGFILE contient l’indicateur PROCESS_TRACE_MODE_RAW_TIMESTAMP , auquel cas la résolution dépend de la valeur du membre Wnode.ClientContext de EVENT_TRACE_PROPERTIES au moment où le contrôleur a créé la session.

DUMMYUNIONNAME3

DUMMYUNIONNAME3.Guid

GUID de classe de trace d’événements. Vous pouvez utiliser le GUID de classe pour identifier une catégorie d’événements et le membre Class.Type pour identifier un événement dans la catégorie d’événements.

Vous pouvez également utiliser le membre GuidPtr pour spécifier le GUID de classe.

Windows XP et Windows 2000 : Le GUID de classe doit avoir été inscrit précédemment à l’aide de la fonction RegisterTraceGuids .

DUMMYUNIONNAME3.GuidPtr

Pointeur vers un GUID de classe de trace d’événements. Vous pouvez également utiliser le membre GUID pour spécifier le GUID de classe.

Lorsque l’événement est écrit, ETW utilise le pointeur pour copier le GUID vers l’événement (le GUID est inclus dans l’événement, et non dans le pointeur).

Si vous utilisez ce membre, le membre Flags doit également contenir WNODE_FLAG_USE_GUID_PTR.

DUMMYUNIONNAME4

DUMMYUNIONNAME4.DUMMYSTRUCTNAME

DUMMYUNIONNAME4.DUMMYSTRUCTNAME.KernelTime

Temps d’exécution écoulé pour les instructions en mode noyau, en unités de temps processeur. Si vous utilisez une session privée, utilisez plutôt la valeur dans le membre ProcessorTime . Pour plus d'informations, consultez la section Notes.

DUMMYUNIONNAME4.DUMMYSTRUCTNAME.UserTime

Temps d’exécution écoulé pour les instructions en mode utilisateur, en unités de temps processeur. Si vous utilisez une session privée, utilisez plutôt la valeur dans le membre ProcessorTime . Pour plus d'informations, consultez la section Notes.

DUMMYUNIONNAME4.ProcessorTime

Pour les sessions privées, le temps d’exécution écoulé pour les instructions en mode utilisateur, dans les graduations du processeur.

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2.ClientContext

Réservé.

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2.Flags

Vous devez définir ce membre sur WNODE_FLAG_TRACED_GUID, et vous pouvez éventuellement spécifier n’importe quelle combinaison des éléments suivants.

• WNODE_FLAG_USE_GUID_PTR : spécifiez si le membre GuidPtr contient le GUID de classe.

• WNODE_FLAG_USE_MOF_PTR : spécifiez si un tableau de structures MOF_FIELD contient les données d’événement ajoutées à cette structure. Le nombre d’éléments dans le tableau est limité à MAX_MOF_FIELDS.

Remarques

Veillez à initialiser la mémoire de cette structure sur zéro avant de définir des membres.

Vous pouvez utiliser les membres KernelTime et UserTime pour déterminer le coût du processeur en unités pour un ensemble d’instructions (les valeurs indiquent l’utilisation du processeur facturée à ce thread au moment de la journalisation). Par exemple, si l’événement A et l’événement B sont journalisés consécutivement par le même thread et qu’ils ont les numéros d’utilisation du processeur 150 et 175, l’activité effectuée par ce thread entre les événements A et B coûte 25 unités de temps processeur (175 à 150).

Le TimerResolution de la structure TRACE_LOGFILE_HEADER contient la résolution du minuteur d’utilisation du processeur en unités de 100 nanosecondes. Vous pouvez utiliser la résolution du minuteur avec les valeurs d’heure du noyau et de temps utilisateur pour déterminer la durée processeur utilisée par l’ensemble d’instructions. Par exemple, si la résolution du minuteur est de 156 250, 25 unités de temps processeur est de 0,39 seconde (156 250 * 25 * 100 / 1 000 000 000 000). Il s’agit de la quantité de temps processeur (temps d’horloge mural non écoulé) utilisée par l’ensemble d’instructions entre les événements A et B.

Notez toutefois que la résolution du minuteur d’utilisation du processeur est généralement très faible (environ 10 millisecondes ou plus). Par conséquent, les numéros d’utilisation du processeur ne peuvent pas être utilisés pour prendre en compte l’utilisation du temps processeur entre les threads avec une précision élevée. Au lieu de cela, ils conviennent pour une analyse statistique à long terme.

Configuration requise

Voir aussi

EVENT_TRACE

EventCallback

TraceEvent