ENABLE_TRACE_PARAMETERS structure (evntrace.h)

Article
08/23/2023

La structure ENABLE_TRACE_PARAMETERS contient des informations utilisées pour activer un fournisseur via EnableTraceEx2.

Syntaxe

typedef struct _ENABLE_TRACE_PARAMETERS {
  ULONG                    Version;
  ULONG                    EnableProperty;
  ULONG                    ControlFlags;
  GUID                     SourceId;
  PEVENT_FILTER_DESCRIPTOR EnableFilterDesc;
  ULONG                    FilterDescCount;
} ENABLE_TRACE_PARAMETERS, *PENABLE_TRACE_PARAMETERS;

Membres

Version

Définissez sur ENABLE_TRACE_PARAMETERS_VERSION_2 (2).

EnableProperty

Paramètres facultatifs que ETW peut inclure lors de l’écriture de l’événement. Certains paramètres écrivent des données supplémentaires dans la section d’élément de données étendu de chaque événement. D’autres paramètres contrôlent les événements qui seront inclus dans la trace. Pour utiliser ces paramètres facultatifs, spécifiez un ou plusieurs des indicateurs suivants. Sinon, définissez sur zéro.

EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0

Filtre les événements où le mot clé de l’événement est 0.

Pris en charge sur Windows 10, version 1507 et ultérieure. Cela est également pris en charge sur Windows 8.1 et Windows 7 avec SP1 via un correctif.
EVENT_ENABLE_PROPERTY_PROVIDER_GROUP

Indique que cet appel à EnableTraceEx2 doit activer un groupe de fournisseurs plutôt qu’un fournisseur d’événements individuel.

Pris en charge sur Windows 10, version 1507 et ultérieure. Cela est également pris en charge sur Windows 8.1 et Windows 7 avec SP1 via un correctif.
EVENT_ENABLE_PROPERTY_PROCESS_START_KEY

Incluez la clé de démarrage du processus dans les données étendues.

La clé de démarrage du processus est un numéro de séquence qui identifie le processus. Bien que l’ID de processus puisse être réutilisé au sein d’une session, la clé de démarrage du processus est garantie unique dans la session de démarrage actuelle.

Pris en charge sur Windows 10, version 1507 et ultérieure. Cela est également pris en charge sur Windows 8.1 et Windows 7 avec SP1 via un correctif.
EVENT_ENABLE_PROPERTY_EVENT_KEY

Incluez la clé d’événement dans les données étendues.

La clé d’événement est un identificateur unique pour l’événement instance qui sera constante sur plusieurs sessions de suivi à l’écoute de cet événement. Il peut être utilisé pour mettre en corrélation des sessions de suivi simultanées.

Pris en charge sur Windows 10, version 1507 et ultérieure.
EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE

Filtre tous les événements marqués comme un événement InPrivate ou qui proviennent d’un processus marqué comme InPrivate.

InPrivate implique que l’événement ou le processus contient des données qui seraient considérées comme privées ou personnelles. C’est au processus ou à l’événement de se désigner lui-même comme InPrivate pour que cela fonctionne.

Pris en charge sur Windows 10, version 1507 et ultérieure.
EVENT_ENABLE_PROPERTY_SID

Incluez l’identificateur de sécurité (SID) de l’utilisateur dans les données étendues de l’événement.

Pris en charge sur Windows Vista et versions ultérieures.
EVENT_ENABLE_PROPERTY_TS_ID

Incluez l’identificateur de session de terminal dans les données étendues de l’événement.

Pris en charge sur Windows Vista et versions ultérieures.
EVENT_ENABLE_PROPERTY_STACK_TRACE

Ajoutez une trace de pile des appels aux données étendues des événements écrits à l’aide d’EventWrite.

Notes

ETW supprime l’événement si la taille totale de l’événement dépasse 64 Ko. Si le fournisseur enregistre des événements de taille proche de 64 Ko maximum, il est possible que l’activation de la capture de pile entraîne la perte de l’événement.

Si la pile est plus longue que le nombre maximal d’images (192), les images sont coupées du bas de la pile.

Pour les consommateurs, les événements incluent le EVENT_EXTENDED_ITEM_STACK_TRACE32 ou EVENT_EXTENDED_ITEM_STACK_TRACE64 élément étendu. Notez que sur les ordinateurs 64 bits, la trace contient les deux piles 64 bits, même si la trace a été démarrée par un contrôleur de trace 32 bits.

Pris en charge sur Windows 7 et versions ultérieures.

ControlFlags

Réservé. Définit la valeur 0.

SourceId

GUID qui identifie de manière unique l’appelant qui active ou désactive le fournisseur. Si le fournisseur n’implémente pas EnableCallback, le GUID n’est pas utilisé.

EnableFilterDesc

Pointeur vers un tableau de structures EVENT_FILTER_DESCRIPTOR qui pointe vers les données de filtre. Le nombre d’éléments dans le tableau est spécifié dans le membre FilterDescCount . Il ne peut y avoir qu’un seul descripteur pour chaque type de filtre, tel que spécifié par le membre Type de la structure EVENT_FILTER_DESCRIPTOR .

FilterDescCount

Nombre d’éléments (filtres) dans le tableau EVENT_FILTER_DESCRIPTOR pointé par le membre EnableFilterDesc .

Le membre FilterDescCount doit correspondre au nombre de structures EVENT_FILTER_DESCRIPTOR dans le tableau vers lequel pointe le membre EnableFilterDesc .

Notes

La structure ENABLE_TRACE_PARAMETERS est une structure version 2 qui remplace la structure ENABLE_TRACE_PARAMETERS_V1 .

Windows 8.1, Windows Server 2012 R2 et versions ultérieures : les filtres de charge utile, d’étendue et de procédure de pile d’événements peuvent être utilisés par la fonction EnableTraceEx2 et les structures ENABLE_TRACE_PARAMETERS et EVENT_FILTER_DESCRIPTOR pour filtrer sur des conditions spécifiques dans une session d’enregistreur d’événements. Pour plus d’informations sur les filtres de charge utile d’événement, consultez les fonctions EnableTraceEx2, TdhCreatePayloadFilter et TdhAggregatePayloadFilters , ainsi que les structures EVENT_FILTER_DESCRIPTOR et PAYLOAD_FILTER_PREDICATE .

En règle générale, sur les ordinateurs 64 bits, vous ne pouvez pas capturer la pile du noyau dans certains contextes lorsque les erreurs de page ne sont pas autorisées. Pour activer la marche à pas de la pile du noyau sur x64, définissez la valeur de Registre Gestion de la DisablePagingExecutive mémoire sur 1. La DisablePagingExecutive valeur de Registre se trouve sous la clé de Registre suivante : HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management. Cela ne doit être effectué qu’à des fins de diagnostic temporaire, car cela augmente l’utilisation de la mémoire du système.

Spécifications


Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
En-tête	evntrace.h