Partager via

Configuration et démarrage d’une session de suivi d’événements

  • Article

Pour configurer une session de suivi d’événements, utilisez la structure EVENT_TRACE_PROPERTIES pour spécifier les propriétés de la session. La mémoire que vous allouez à la structure EVENT_TRACE_PROPERTIES doit être suffisamment grande pour contenir également les noms de fichiers de session et de journal qui suivent la structure en mémoire.

Après avoir spécifié les propriétés de la session, appelez la fonction StartTrace pour démarrer la session. Si la fonction réussit, le paramètre SessionHandle contient le handle de session et la propriété LoggerNameOffset contient le décalage par rapport au nom de la session.

Pour activer les fournisseurs que vous souhaitez enregistrer des événements dans votre session, appelez la fonction EnableTrace pour activer les fournisseurs classiques et la fonction EnableTraceEx pour activer les fournisseurs basés sur un manifeste . Pour activer le filtrage des fournisseurs dont vous souhaitez enregistrer les événements dans votre session sur des conditions spécifiques sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures, appelez la fonction EnableTraceEx2.

En outre, vous pouvez également suivre des informations supplémentaires sur un événement avec un appel à la fonction TraceSetInformation . TraceSetInformation place des informations de trace supplémentaires dans la section de données étendues d’un événement et peut inclure des informations telles que les informations de version de trace ou les fournisseurs actuellement inscrits sur le système. Pour plus d’informations, consultez Récupération de données de suivi d’événements supplémentaires.

Jusqu’à huit sessions de trace peuvent activer et recevoir des événements du même fournisseur basé sur le manifeste . Toutefois, une seule session de trace peut activer un fournisseur classique . Si plusieurs sessions de suivi tentent d’activer un fournisseur classique, la première session cesse de recevoir des événements lorsque la deuxième session active le fournisseur. Par exemple, si la session A a activé le fournisseur 1, puis la session B avec le fournisseur 1, seule la session B reçoit les événements du fournisseur 1.

Vous pouvez utiliser l’une des trois fonctions pour activer un fournisseur, mais vous risquez de perdre des fonctionnalités si vous utilisez EnableTrace pour activer un fournisseur basé sur un manifeste, car vous ne serez pas en mesure de fournir une valeur MatchAllKeyword, de spécifier des éléments de données étendus à inclure dans l’événement ou de fournir des données de filtre définies par le fournisseur. Pour plus d’informations, consultez la section Notes de chaque fonction.

Sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures, les filtres de charge utile d’événement, d’étendue et de marche de pile 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 TdhCreatePayloadFilter et TdhAggregatePayloadFilters et les structures ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTOR et PAYLOAD_FILTER_PREDICATE .

Pour déterminer le niveau et les mots clés utilisés pour activer un fournisseur basé sur un manifeste, utilisez l’une des commandes suivantes :

  • Logmanqueryprovider-name
  • Wevtutilgpprovider-name

Les commandes répertorient uniquement le niveau et les mots clés. Le fournisseur doit documenter les exigences de données de filtre pour les contrôleurs potentiels.

Pour énumérer les fournisseurs basés sur un manifeste, utilisez Wevtutilep.

Pour les fournisseurs classiques, il incombe au fournisseur de documenter et de mettre à la disposition des contrôleurs potentiels les niveaux de gravité ou les indicateurs d’activation qu’il prend en charge. Si le fournisseur souhaite être activé par un contrôleur, il doit accepter 0 pour le niveau de gravité et activer les indicateurs et interpréter 0 comme une demande d’exécution de la journalisation par défaut (quelle qu’elle soit).

Vous pouvez activer le fournisseur avant ou après l’inscription du fournisseur. Après avoir activé le fournisseur, ETW appelle la fonction de rappel du fournisseur. Si le fournisseur n’est pas inscrit, ETW appelle la fonction de rappel du fournisseur après s’être inscrit.

Vous pouvez également utiliser la fonction EnableTrace pour désactiver le fournisseur (l’empêcher de journaliser les événements dans votre session) ou pour mettre à jour le niveau de journalisation ou activer les indicateurs du fournisseur. Avec la fonction EnableTraceEx , vous pouvez désactiver le fournisseur ou mettre à jour le niveau, les mots clés, les données étendues et filtrer les données. Chaque fois que vous appelez la fonction EnableTrace ou EnableTraceEx , ETW appelle la fonction de rappel du fournisseur. Le fournisseur reste activé pour la session jusqu’à ce que la session désactive le fournisseur.

Pour arrêter la session de suivi après la collecte des événements, appelez la fonction ControlTrace et passez EVENT_TRACE_CONTROL_STOP comme code de contrôle. Pour spécifier la session à arrêter, vous pouvez passer le handle de session de suivi d’événements obtenu à partir d’un appel antérieur à la fonction StartTrace , ou le nom d’une session précédemment démarrée. Veillez à désactiver tous les fournisseurs avant d’arrêter la session. Si vous arrêtez la session avant de désactiver le fournisseur, ETW le désactive et tente d’appeler la fonction de rappel de contrôle du fournisseur. Si l’application qui a démarré la session se termine sans désactiver le fournisseur ou appeler la fonction ControlTrace , le fournisseur reste activé.

Si ControlTrace réussit, les propriétés de session sont mises à jour pour refléter les valeurs de propriété finales et exécuter des statistiques pour la session de suivi d’événements.

Pour obtenir un exemple qui démarre une session de suivi d’événements, consultez les rubriques suivantes :

Pour plus d’informations sur le démarrage d’une session de trace, consultez l’une des rubriques suivantes :

Configuration et démarrage d’une session d’enregistreur d’événements privés

Configuration et démarrage d’une session SystemTraceProvider

Configuration et démarrage d’une session de journal automatique

Configuration et démarrage de la session d’enregistreur d’événements du noyau NT

ControlTrace

EnableTrace

EnableTraceEx

EnableTraceEx2

ENABLE_TRACE_PARAMETERS

EVENT_FILTER_DESCRIPTOR

EVENT_TRACE_PROPERTIES

PAYLOAD_FILTER_PREDICATE

StartTrace

TdhAggregatePayloadFilters

TdhCreatePayloadFilter

Mise à jour d’une session de suivi d’événements