Configuration et démarrage d’une session de suivi d’événements
Pour configurer une session de suivi d’événements, utilisez la structure EVENT\_TRACE\_PROPERTIES pour indiquer les propriétés de la session. La mémoire que vous attribuez à la structure EVENT_TRACE_PROPERTIES doit être assez grande pour contenir également les noms de fichier journal et de session qui suivent la structure en mémoire.
Une fois que vous avez indiqué les propriétés de la session, appelez la fonction StartTrace pour démarrer la session. Si la fonction aboutit, le paramètre SessionHandle contient le handle de session et la propriété LoggerNameOffset contient le décalage du nom de la session.
Pour activer les fournisseurs dont vous souhaitez enregistrer les événements dans votre session, appelez la fonction EnableTrace pour activer les fournisseurs habituels, et la fonction EnableTraceEx pour activer les fournisseurs basés sur des manifestes. Pour activer les fournisseurs qui souhaitent que les événements de journalisation de votre session soient filtrés en fonction de conditions spécifiques sous Windows 8.1, Windows Server 2012 R2 et versions ultérieures, appelez la fonction EnableTraceEx2.
Par ailleurs, vous pouvez également suivre des informations supplémentaires sur un événement en appelant la fonction TraceSetInformation. TraceSetInformation place des informations de suivi supplémentaires dans la section de données étendues d’un événement, et peut inclure des informations comme les informations de version de suivi, ou encore les fournisseurs actuellement inscrits sur le système. Pour en savoir plus, consultez Récupérer des données de suivi d'événement supplémentaires.
Jusqu’à huit sessions de suivi peuvent activer et recevoir des événements du même fournisseur basé sur un manifeste. Toutefois, une seule session de trace peut activer un fournisseur classique. Si plusieurs sessions de suivi essaient 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 et que la session B active ensuite le fournisseur 1, seule la session B recevra les événements du fournisseur 1.
Vous pouvez utiliser l’une des trois fonctions pour activer un fournisseur. Toutefois, les performances risquent de se détériorer si vous utilisez EnableTrace pour activer un fournisseur basé sur un manifeste. En effet, vous ne pourrez pas fournir une valeur MatchAllKeyword, spécifier des éléments de données étendus à inclure dans l'événement ni fournir des données de filtrage définies par le fournisseur. Pour plus de détails, consultez la section Notes de chaque fonction.
Sous 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 la pile peuvent être utilisés par la fonction EnableTraceEx2 et les structures ENABLE_TRACE_PARAMETERS et EVENT_FILTER_DESCRIPTOR afin de filtrer selon des conditions spécifiques dans une session d'enregistreur d'événements. Pour en savoir plus sur les filtres de charge utile d'événement, consultez les fonctions TdhCreatePayloadFilter et TdhAggregatePayloadFilters ainsi que les structures ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTOR et PAYLOAD_FILTER_PREDICATE.
Pour déterminer le niveau et les mots clés utilisés afin d'activer un fournisseur basé sur un manifeste, utilisez l’une des commandes suivantes :
- Logman query provider-name
- Wevtutil gp provider-name
Ces commandes listent 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 Wevtutil ep.
Pour les fournisseurs classiques, il incombe au fournisseur de documenter et de mettre à la disposition des contrôleurs potentiels les niveaux de gravité ou d’activer les indicateurs pris en charge. Si le fournisseur souhaite être activé par n’importe quel contrôleur, il doit définir le niveau de gravité sur 0, activer les indicateurs et interpréter 0 en tant que demande d’exécution de journalisation par défaut (quelle qu'elle soit).
Vous pouvez activer le fournisseur avant ou après qu'il se soit enregistré. Après avoir activé le fournisseur, ETW appelle la fonction de rappel du fournisseur. Si le fournisseur n’est pas enregistré, ETW appelle la fonction de rappel du fournisseur une fois celui-ci enregistré.
Vous pouvez également utiliser la fonction EnableTrace pour désactiver le fournisseur (l'empêcher d'enregistrer des événements dans votre session), ou bien pour mettre à jour le niveau d'enregistrement ou les indicateurs d'activation du fournisseur. La fonction EnableTraceEx vous permet de désactiver le fournisseur ou de modifier le niveau, les mots clés, les données étendues et les données de filtre. Chaque fois que vous appelez la fonction EnableTrace ou EnableTraceEx, ETW appelle la fonction de rappel du fournisseur. Ce dernier reste activé pour la session jusqu’à ce qu'elle le désactive.
Pour arrêter la session de suivi après avoir collecté des événements, appelez la fonction ControlTrace et transmettez EVENT_TRACE_CONTROL_STOP en tant que code de contrôle. Pour indiquer la session à arrêter, vous pouvez transmettre 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 démarrée précédemment. Veillez à désactiver tous les fournisseurs avant de mettre fin à la session. Si vous mettez fin à la session avant de désactiver le fournisseur, ETW désactive le fournisseur et tente d’appeler la fonction de rappel de contrôle du fournisseur. Si l’application qui a démarré la session se termine, mais que vous n'avez pas désactivé le fournisseur ni appelé la fonction ControlTrace, le fournisseur reste activé.
Si ControlTrace aboutit, les propriétés de session sont modifiées pour refléter les valeurs de propriété finales et exécuter des analyses statistiques pour la session de suivi d’événements.
Pour obtenir un exemple de démarrage de session de suivi d’événements, consultez les rubriques suivantes :
- Exemple d'utilisateur qui crée une session et active un fournisseur basé sur un manifeste : il démarre une session de suivi, active un fournisseur basé sur un manifeste, désactive ce fournisseur, puis met fin à la session.
Pour en savoir plus sur le démarrage d’une session de suivi, consultez l’une des rubriques suivantes :
- Configuration et démarrage d’une session SystemTraceProvider
- Configuration et démarrage de l’enregistreur d’événements du noyau NT
- Configuration et démarrage d’une session AutoLogger
- Configuration et démarrage de la session d’enregistreur d’événements global
- Configuration et démarrage d’une session d’enregistreur d’événements privés
Rubriques connexes
-
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 de l’enregistreur d’événements du noyau NT