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).
| Valeur | Signification |
|---|---|
| TRACE_LEVEL_CRITICAL (1) | Événements de sortie ou d’arrêt anormaux |
| TRACE_LEVEL_ERROR (2) | Événements d’erreur grave |
| TRACE_LEVEL_WARNING (3) | Événements d’avertissement tels que les échecs d’allocation |
| TRACE_LEVEL_INFORMATION (4) | Événements sans erreur, tels que les événements d’entrée ou de sortie |
| TRACE_LEVEL_VERBOSE (5) | Événements de trace détaillés |
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
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| En-tête | evntrace.h |