EventActivityIdControl, fonction (evntprov.h)

  • Article

Crée, interroge et définit des identificateurs d’activité à utiliser dans les événements ETW.

Syntaxe

ULONG EVNTAPI EventActivityIdControl(
  [in]      ULONG  ControlCode,
  [in, out] LPGUID ActivityId
);

Paramètres

[in] ControlCode

Code de contrôle qui spécifie l’opération à effectuer.

  • EVENT_ACTIVITY_CTRL_GET_ID

    Définit le paramètre ActivityId sur la valeur de l’ID d’activité du thread actuel.

  • EVENT_ACTIVITY_CTRL_SET_ID

    Définit l’ID d’activité du thread actuel sur la valeur du paramètre ActivityId .

  • EVENT_ACTIVITY_CTRL_CREATE_ID

    Définit le paramètre ActivityId sur la valeur d’un ID d’activité unique nouvellement généré localement.

  • EVENT_ACTIVITY_CTRL_GET_SET_ID

    Permute les valeurs du paramètre ActivityId et l’ID d’activité du thread actuel. (Enregistre la valeur de l’ID d’activité du thread actuel, définit l’ID d’activité du thread actuel sur la valeur du paramètre ActivityId , puis définit le paramètre ActivityId sur la valeur enregistrée.)

  • EVENT_ACTIVITY_CTRL_CREATE_SET_ID

    Définit le paramètre ActivityId sur la valeur de l’ID d’activité du thread actuel, puis définit l’ID d’activité du thread actuel sur la valeur d’un ID d’activité unique localement nouvellement généré.

[in, out] ActivityId

Pointeur vers une mémoire tampon qui contient un ID d’activité 128 bits. Cette mémoire tampon peut être en lecture à partir de et/ou écrite sur, selon la valeur du paramètre ControlCode .

Valeur retournée

Retourne ERROR_SUCCESS en cas de réussite.

Remarques

Les événements ETW écrits à l’aide de l’une des API EventWrite contiennent un champ « ID d’activité » 128 bits et peuvent éventuellement contenir un champ « ID d’activité associé » 128 bits. Les outils de traitement des traces peuvent utiliser les valeurs de ces champs pour organiser les événements en groupes appelés activités.

  • Tous les événements dont l’ID d’activité est égal à zéro (c’est-à-dire GUID_NULL) ne font pas partie d’une activité.
  • Tous les événements qui ont un ID d’activité différent de zéro particulier sont supposés faire partie de la même activité.
  • Pour indiquer le début de l’activité, le fournisseur doit définir Opcode sur WINEVENT_OPCODE_START pour le premier événement avec un ID d’activité différent de zéro (l’événement de début ). Si l’activité est imbriquée logiquement dans une autre activité, le fournisseur doit définir le champ d’ID d’activité associé de l’événement de démarrage sur l’ID de l’activité parente.
  • Pour indiquer la fin de l’activité, le fournisseur doit définir Opcode sur WINEVENT_OPCODE_STOP pour le dernier événement avec un ID d’activité différent de zéro (l’événement d’arrêt ).

Pour que les ID d’activité soient utiles, les ID d’activité nouvellement générés doivent être uniques localement, c’est-à-dire que le même ID ne doit pas être généré deux fois dans la trace.

Vous pouvez créer des ID d’activité à l’aide d’EventActivityIdControl, qui génère des ID localement uniques qui sont garantis comme étant uniques dans tous les processus sur le système local jusqu’à ce que le système redémarre. Vous pouvez également utiliser un GUID (identificateur global unique) comme ID d’activité. Vous pouvez créer un GUID à l’aide d’une API telle que UuidCreate.

Les threads en mode utilisateur ont une valeur d’ID d’activité de thread local 128 bits (l’ID d’activité du thread). L’ID d’activité du thread est initialisé à 0 (c’est-à-dire GUID_NULL) lors de la création du thread. L’ID d’activité du thread peut être lu ou mis à jour à l’aide d’EventActivityIdControl. L’ID d’activité de thread sera utilisé comme ID d’activité pour tous les événements écrits par EventWrite et pour tous les événements écrits par EventWriteTransfer ou EventWriteEx où le paramètre ActivityId est NULL.

Important

Une fonction qui modifie l’ID d’activité d’un thread doit veiller à restaurer l’ID d’activité d’origine avant de quitter. Sinon, les modifications apportées à l’ID d’activité du thread par la fonction interfèrent avec les activités des composants qui appellent la fonction.

Utilisation d’un ID d’activité spécifié explicitement

Dans les cas où vos activités ne sont pas limitées à un seul thread ou si vous souhaitez éviter la possibilité d’interférence d’autres composants qui remplacent l’ID d’activité de votre thread, vous pouvez spécifier explicitement les activités d’événement via le champ ActivityIdd’EventWriteTransfer ou EventWriteEx au lieu d’utiliser l’ID d’activité de thread automatique.

Si vous utilisez des manifestes et le compilateur de messages pour écrire des événements, les macros générées par MC.exe -um utilisent l’ID d’activité du thread, tandis que les macros générées par MC.exe -km prennent en charge un paramètre d’ID d’activité. À l’origine, les -um macros fonctionnaient uniquement en mode utilisateur, et les -km macros fonctionnaient uniquement en mode noyau, de sorte que le code en mode utilisateur ne pouvait utiliser que l’ID d’activité du thread actuel. Toutefois, à compter de MC.exe version 10.0.17741, les macros générées par MC.exe -km peuvent être utilisées pour le mode utilisateur et le mode noyau. Vous pouvez donc utiliser MC.exe -km pour générer des macros qui acceptent un paramètre d’ID d’activité. (Le code généré par mc ne prend pas en charge la définition de l’ID d’activité associé à un événement.)

Si vous utilisez TraceLoggingProvider.h pour écrire des événements, la macro TraceLoggingWrite utilise l’ID d’activité du thread, tandis que TraceLoggingWriteActivity accepte les paramètres pour l’ID d’activité et l’ID d’activité associé. Vous pouvez également utiliser les classes C++ dans TraceLoggingActivity.h pour vos activités TraceLogging.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows Vista [applications de bureau | applications UWP]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête evntprov.h
Bibliothèque Advapi32.lib
DLL Advapi32.dll

Voir aussi

EventWriteTransfer