structure EVENT_FILTER_DESCRIPTOR (evntprov.h)

Article
08/23/2023

La structure EVENT_FILTER_DESCRIPTOR définit les données de filtre qu’une session transmet à la fonction de rappel d’activation du fournisseur.

Syntaxe

typedef struct _EVENT_FILTER_DESCRIPTOR {
  ULONGLONG Ptr;
  ULONG     Size;
  ULONG     Type;
} EVENT_FILTER_DESCRIPTOR, *PEVENT_FILTER_DESCRIPTOR;

Membres

Ptr

Pointeur vers les données de filtre pour le type de filtre spécifié dans le membre Type .

Si le membre Type est défini sur EVENT_FILTER_TYPE_PID, le membre Ptr pointe vers un tableau d’ID de processus (PIDs).

Si le membre Type est défini sur EVENT_FILTER_TYPE_EVENT_ID, le membre Ptr pointe vers une structure de EVENT_FILTER_EVENT_ID qui contient un tableau d’ID d’événement et une valeur booléenne qui détermine si le suivi est activé ou désactivé pour les ID d’événement spécifiés.

Si le membre Type est défini sur EVENT_FILTER_TYPE_STACKWALK, le membre Ptr pointe vers une structure EVENT_FILTER_EVENT_ID qui contient un tableau d’ID d’événement et une valeur booléenne qui détermine si le suivi de la pile est activé ou désactivé pour les ID d’événement spécifiés.

Si le membre Type est défini sur EVENT_FILTER_TYPE_SCHEMATIZED, consultez la structure EVENT_FILTER_HEADER pour plus d’informations sur la construction du filtre.

Size

Taille des données, en octets.

La limite de taille maximale des données varie en fonction du membre Type spécifié (le type du filtre). La taille maximale des données, en octets, pour de nombreux types de filtres est limitée à MAX_EVENT_FILTER_DATA_SIZE, définie dans le fichier d’en-tête evntprov.h sur 1024.

Type

Valeur définie par le fournisseur qui identifie le filtre. Pour les filtres définis dans un manifeste d’instrumentation, définissez ce membre sur EVENT_FILTER_TYPE_SCHEMATIZED.

Les valeurs possibles pour ce membre sont définies dans le fichier d’en-tête evntprov.h .

EVENT_FILTER_TYPE_NONE (0x00000000)

Aucun filtre.
EVENT_FILTER_TYPE_SCHEMATIZED (0x80000000)

Filtre schématisé.

Il s’agit de la configuration de filtrage traditionnelle également appelée filtrage côté fournisseur. Le contrôleur définit un ensemble personnalisé de filtres en tant qu’objet binaire passé au fournisseur dans l’appel EnableTrace, EnableTraceEx ou EnableTraceEx2 . Il incombe au contrôleur et au fournisseur de définir et d’interpréter ces filtres et le contrôleur ne doit consigner que les événements applicables. Cela nécessite un couplage rapproché du contrôleur et du fournisseur, car le type et le format de l’objet binaire de ce qui peut être filtré ne sont pas définis. La fonction TdhEnumerateProviderFilters peut être utilisée pour récupérer les filtres définis dans un manifeste.

Pour plus d’informations sur les filtres schématisés, consultez Définition de filtres.
EVENT_FILTER_TYPE_SYSTEM_FLAGS (0x80000001)

Réservé à un usage interne.
EVENT_FILTER_TYPE_TRACEHANDLE (0x80000002)

Utilisé pour capturer un rundown d’une session de trace particulière. Le paramètre ControlCode passé à la fonction EnableTraceEx doit être défini sur EVENT_CONTROL_CODE_CAPTURE_STATE et le paramètre ProviderId doit être le SystemTraceControlGuid. La structure EVENT_FILTER_DESCRIPTOR doit pointer vers une seule TRACEHANDLE qui représente une session ETW actuelle. Une exécution est effectuée pour cette session particulière.
EVENT_FILTER_TYPE_PID (0x80000004)

ID de processus. Il s’agit de l’un des filtres d’étendue.

Le filtrage des événements ETW en fonction des ID de processus entraîne un flux d’événements (fichier ou temps réel) qui contient uniquement les événements des fournisseurs dans les processus spécifiés. Elle active uniquement le fournisseur dans les processus dont les PID sont fournis. La liste des PID correspond aux PID des processus en cours d’exécution au moment où EnableTraceEx2 est appelé et active le fournisseur dans tous les processus (pour lesquels des PID sont fournis) à ce moment particulier. La liste des PID ne sera pas stockée dans la session. Par conséquent, lorsqu’un processus est arrêté et réapparaît, le fournisseur dans celui-ci n’est pas automatiquement activé pour la session de trace. L’objet blob de filtre basé sur les PIDs n’est valide que pour une session d’enregistreur d’événements en mode noyau, car la session d’enregistreur d’événements privé s’exécute à l’intérieur d’un processus en mode utilisateur.

Le nombre maximal d’ID de processus pouvant être filtrés est limité par MAX_EVENT_FILTER_PID_COUNT défini dans le fichier d’en-tête evntprov.h à 8.

Si un filtre d’ID de processus est fourni, le fournisseur est activé uniquement dans les processus en mode utilisateur. Si le même fournisseur est inscrit par un pilote en mode noyau, il ne sera pas activé.

Il est utilisé avec EVENT_TRACE_PROPERTIES_V2 pour les enregistreurs d’événements privés à l’échelle du système.
EVENT_FILTER_TYPE_EXECUTABLE_NAME (0x80000008)

Nom de fichier de l’exécutable. Il s’agit de l’un des filtres d’étendue.

Il est utilisé avec EVENT_TRACE_PROPERTIES_V2 pour les enregistreurs d’événements privés à l’échelle du système.
EVENT_FILTER_TYPE_PACKAGE_ID (0x80000010)

ID du package. Il s’agit de l’un des filtres d’étendue

Cela peut être utilisé pour filtrer les fournisseurs sur les événements émis à partir d’un package d’application du Windows Store particulier.
EVENT_FILTER_TYPE_PACKAGE_APP_ID (0x80000020)

ID d’application relative du package (PRAID). Il s’agit de l’un des filtres d’étendue

Cela peut être utilisé pour filtrer les fournisseurs sur les événements émis à partir d’un package d’application du Windows Store particulier.
EVENT_FILTER_TYPE_PAYLOAD (0x80000100)

Charge utile de l’événement (contenu de l’événement).

La taille maximale des données, en octets, pour un filtre de charge utile d’événement est limitée à MAX_EVENT_FILTER_PAYLOAD_SIZE définie dans le fichier d’en-tête evntprov.h à 4096.
EVENT_FILTER_TYPE_EVENT_ID (0x80000200)

ID de l’événement.

Cette fonctionnalité permet d’activer ou de désactiver le filtrage pour une liste d’événements. Le filtre fourni comprend une structure EVENT_FILTER_EVENT_ID qui contient un tableau d’ID d’événement et une valeur booléenne qui indique s’il faut activer ou désactiver le filtrage pour les événements spécifiés. Chaque appel d’écriture d’événement passe rapidement par ce tableau pour savoir si l’activation ou la désactivation de la journalisation de l’événement.

Lorsqu’il est appliqué à un fournisseur TraceLogging, ce filtre est ignoré, car les événements TraceLogging n’ont pas d’ID d’événement statiques.

Le nombre maximal d’ID d’événement autorisés dans la structure EVENT_FILTER_EVENT_ID est limité par MAX_EVENT_FILTER_EVENT_ID_COUNT défini dans le fichier d’en-tête evntprov.h à 64.
EVENT_FILTER_TYPE_EVENT_NAME (0x80000400)

Nom de l’événement TraceLogging.

Cette fonctionnalité permet d’activer ou de désactiver les événements TraceLogging en fonction de leur nom. Le filtre fourni comprend une structure de EVENT_FILTER_EVENT_NAME qui contient un tableau de noms d’événements, des masques de bits mot clé et un niveau sur lequel filtrer, ainsi qu’une valeur booléenne qui indique s’il faut activer ou désactiver les événements décrits. Lorsqu’il est appliqué à un fournisseur non TraceLogging, ce filtre est ignoré, car ces événements n’ont pas de noms spécifiés dans leur charge utile.

Note: Disponible sur Windows 10, version 1709 et ultérieure.
EVENT_FILTER_TYPE_STACKWALK (0x80001000)

Une marche de pile.

Lorsque la marche à pied de la pile est activée pour un fournisseur, la pile est capturée pour tous les événements générés par le fournisseur. La plupart du temps, l’utilisateur n’est intéressé par la pile qu’à partir d’un certain nombre d’événements.

Cette fonctionnalité permet d’activer ou de désactiver la marche de la pile sur une liste d’événements. Le filtre fourni comprend une structure EVENT_FILTER_EVENT_ID qui contient un tableau d’ID d’événement et une valeur booléenne qui indique s’il faut activer ou désactiver la capture de pile pour les événements spécifiés. Chaque appel d’écriture d’événement passe rapidement par ce tableau pour déterminer si la pile doit être capturée ou non.

Lorsqu’il est appliqué à un fournisseur TraceLogging, ce filtre est ignoré, car les événements TraceLogging n’ont pas d’ID d’événement statiques.

Si vous choisissez d’utiliser ce filtre, vous devez toujours spécifier EVENT_ENABLE_PROPERTY_STACK_TRACE dans la structure ENABLE_TRACE_PARAMETERS lors de l’activation du fournisseur pour que toutes les piles soient collectées à partir d’un fournisseur.

Le nombre maximal d’ID d’événement autorisés dans la structure EVENT_FILTER_EVENT_ID est limité par MAX_EVENT_FILTER_EVENT_ID_COUNT défini dans le fichier d’en-tête evntprov.h à 64.

Note: Disponible sur Windows 10, version 1709 et ultérieure.
EVENT_FILTER_TYPE_STACKWALK_NAME (0x80002000)

Nom de l’événement TraceLogging.

Cette fonctionnalité permet de filtrer la collection de pile pour les événements TraceLogging en fonction des noms d’événements. Le filtre fourni comprend une structure de EVENT_FILTER_EVENT_NAME qui contient un tableau de noms d’événements, des mot clé des masques de bits et un niveau sur lequel filtrer, ainsi qu’une valeur booléenne qui indique s’il faut collecter ou non des piles pour les événements décrits.

Lorsqu’il est appliqué à un fournisseur non TraceLogging, ce filtre est ignoré, car ces événements n’ont pas de noms spécifiés dans leur charge utile.

Si vous choisissez d’utiliser ce filtre, vous devez toujours spécifier EVENT_ENABLE_PROPERTY_STACK_TRACE sur la structure de ENABLE_TRACE_PARAMETERS lors de l’activation du fournisseur pour la collecte des piles à partir d’un fournisseur.

Note: Disponible sur Windows 10, version 1709 et ultérieure.
EVENT_FILTER_TYPE_STACKWALK_LEVEL_KW (0x80004000)

Niveau de l’événement et mot clé.

Cette fonctionnalité permet de filtrer la collection de pile pour les événements en fonction de leur niveau et de leur mot clé. Le filtre fourni comprend une structure EVENT_FILTER_LEVEL_KW qui contient mot clé masque de bits et le niveau sur lequel filtrer, ainsi qu’une valeur booléenne qui indique s’il faut collecter ou non des piles pour les événements décrits.

Si vous choisissez d’utiliser ce filtre, vous devez toujours spécifier EVENT_ENABLE_PROPERTY_STACK_TRACE sur la structure de ENABLE_TRACE_PARAMETERS lors de l’activation du fournisseur pour la collecte des piles à partir d’un fournisseur.

Note: Disponible sur Windows 10, version 1709 et ultérieure.

Notes

Le fournisseur détermine la disposition des données et leur objectif.

Sur 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énements, consultez les fonctions EnableTraceEx2, TdhCreatePayloadFilter et TdhAggregatePayloadFilters , ainsi que les structures ENABLE_TRACE_PARAMETERS et PAYLOAD_FILTER_PREDICATE .

Spécifications


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