EventWriteEx, fonction (evntprov.h)

Écrit un événement ETW avec un ID d’activité, un ID d’activité associé facultatif, des filtres de session et des options spéciales.

Syntaxe

ULONG EVNTAPI EventWriteEx(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG64                Filter,
  [in]           ULONG                  Flags,
  [in, optional] LPCGUID                ActivityId,
  [in, optional] LPCGUID                RelatedActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

Paramètres

[in] RegHandle

Handle d’inscription du fournisseur. Le handle provient d’EventRegister. L’événement généré utilise le ProviderId associé au handle.

[in] EventDescriptor

EVENT_DESCRIPTOR avec des informations sur l’événement (métadonnées), notamment l’ID, la version, le niveau, le mot clé, le canal, le code d’opération et la tâche.

[in] Filter

Valeur de masque de bits 64 bits. Chaque bit défini indique que cet événement doit être exclu d’une session de trace particulière.

Le paramètre Filter est utilisé avec les fournisseurs d’événements qui effectuent un filtrage d’événements personnalisé basé sur filterDatad’EnableCallback.

Définissez Filtre sur zéro si vous ne prenez pas en charge les filtres d’événements personnalisés ou si l’événement doit être écrit dans toutes les sessions de trace. Sinon, définissez Filter sur le bit-OR des identificateurs des sessions qui ne doivent PAS recevoir l’événement.

[in] Flags

Définissez Indicateurs sur zéro pour la gestion normale des événements.

Définissez Indicateurs sur une combinaison de valeurs EVENT_WRITE_FLAG pour la gestion d’événements spéciaux.

• EVENT_WRITE_FLAG_INPRIVATE (0x2)

  Indique que cet événement doit être exclu de tout journal qui a défini l’option EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE .

[in, optional] ActivityId

Pointeur facultatif vers un ID d’activité 128 bits pour cet événement. Si ce n’est pas NULL, EventWriteEx utilise la valeur spécifiée pour l’ID d’activité de l’événement. S’il s’agit de NULL, EventWriteEx utilise l’ID d’activité du thread actuel.

Les outils de traitement des traces peuvent utiliser l’ID d’activité de l’événement pour organiser les événements en groupes appelés activités. Pour plus d’informations sur l’ID d’activité, consultez EventActivityIdControl.

[in, optional] RelatedActivityId

Pointeur facultatif vers un ID d’activité 128 bits qui est le parent de l’activité de cet événement. Si ce n’est pas NULL, EventWriteEx utilise la valeur spécifiée pour l’ID d’activité associé à l’événement. Si cette valeur est NULL, l’événement n’aura pas d’ID d’activité associé. L’ID d’activité associé est généralement défini sur l’événement START de l’activité (le premier événement de l’activité, enregistré avec Opcode = START).

Les outils de traitement des traces peuvent utiliser l’ID d’activité associé de l’événement pour déterminer la relation entre les activités, par exemple, l’activité associée est le parent de l’activité nouvellement démarrée. Pour plus d’informations sur l’ID d’activité associé, consultez EventActivityIdControl.

[in] UserDataCount

Nombre de structures EVENT_DATA_DESCRIPTOR dans UserData. Le nombre maximal est 128.

[in, optional] UserData

Tableau de structures UserDataCountEVENT_DATA_DESCRIPTOR qui décrivent les données à inclure dans l’événement. UserData peut avoir la valeur NULL si UserDataCount est égal à zéro.

Chaque EVENT_DATA_DESCRIPTOR décrit un bloc de mémoire à inclure dans l’événement. Les blocs spécifiés seront concaténés dans l’ordre sans remplissage ni alignement pour former le contenu de l’événement. Si vous utilisez le décodage basé sur un manifeste, le contenu de l’événement doit correspondre à la disposition spécifiée dans le modèle associé à l’événement dans le manifeste.

Valeur retournée

Retourne ERROR_SUCCESS en cas de réussite ou un code d’erreur. Les codes d’erreur possibles sont les suivants :

• ERROR_INVALID_PARAMETER : un ou plusieurs paramètres ne sont pas valides.
• ERROR_INVALID_HANDLE : le handle d’inscription du fournisseur n’est pas valide.
• ERROR_ARITHMETIC_OVERFLOW : la taille de l’événement est supérieure à la valeur maximale autorisée (64 Ko - en-tête).
• ERROR_MORE_DATA : la taille de la mémoire tampon de session est trop petite pour l’événement.
• ERROR_NOT_ENOUGH_MEMORY : se produit lorsque des mémoires tampons remplies tentent de vider sur le disque, mais que les E/S de disque ne se produisent pas assez rapidement. Cela se produit lorsque le disque est lent et que le trafic d’événements est lourd. Finalement, il n’y a plus de mémoires tampons libres (vides) et l’événement est supprimé.
• STATUS_LOG_FILE_FULL : le fichier de lecture en temps réel est plein. Les événements ne sont pas consignés dans la session tant qu’un consommateur en temps réel n’utilise pas les événements du fichier de lecture.

Le code d’erreur est principalement destiné à être utilisé dans les scénarios de débogage et de diagnostic. La plupart du code de production doit continuer à s’exécuter et continuer à signaler des événements même si un événement ETW n’a pas pu être écrit. Les builds de mise en production doivent donc généralement ignorer le code d’erreur.

Remarques

La plupart des fournisseurs d’événements n’appellent pas EventWriteEx directement. Au lieu de cela, la plupart des fournisseurs d’événements sont implémentés à l’aide d’une infrastructure ETW qui encapsule les appels à EventRegister, EventWriteEx et EventUnregister. Par exemple, vous pouvez écrire un manifeste d’événement , puis utiliser le compilateur de messages pour générer du code C/C++ pour les événements, ou vous pouvez utiliser TraceLogging pour éviter d’avoir besoin d’un manifeste.

EventWriteEx acheminera l’événement vers les sessions de suivi appropriées en fonction de l’Id de fournisseur (déterminé à partir de la RegHandle), du niveau, du mot clé et d’autres caractéristiques de l’événement. Si aucune session de trace n’enregistre cet événement, cette fonction ne fait rien et retourne ERROR_SUCCESS.

Pour réduire l’impact sur les performances des événements qui ne sont enregistrés par aucune session de trace, vous pouvez appeler EventEnabled pour déterminer si une session de trace enregistre votre événement avant de préparer les données et d’appeler EventWriteEx.

Un fournisseur peut définir des filtres qu’une session utilise pour filtrer les événements en fonction des données d’événement. Les filtres principaux sont basés sur le niveau et les mots clés. Les fournisseurs d’événements peuvent prendre en charge des filtres plus complexes. Le fournisseur d’événements peut recevoir des informations de filtre à partir du paramètre FilterDatad’EnableCallback. Le fournisseur peut évaluer le filtre et utiliser le paramètre Filter de EventWriteEx pour indiquer que certaines sessions de trace n’ont pas réussi le filtre et ne doivent donc pas recevoir l’événement.

Configuration requise

Voir aussi

EventActivityIdControl

EventRegister

EventWrite

EventWriteTransfer

Écriture d’événements basés sur un manifeste.