Macro TraceLoggingWriteActivity (traceloggingprovider.h)
Émet un événement TraceLogging avec des ID d’activité spécifiés.
Syntaxe
void TraceLoggingWriteActivity(
[in] hProvider,
[in] eventName,
[in, optional] pActivityId,
[in, optional] pRelatedActivityId,
[in, optional] __VA_ARGS__
);
Paramètres
[in] hProvider
Handle du fournisseur TraceLogging à utiliser pour écrire l’événement.
[in] eventName
Nom court et unique à utiliser pour identifier l’événement. Il doit s’agir d’un littéral de chaîne et non d’une variable. Il ne peut pas contenir de caractères incorporés '\0' .
[in, optional] pActivityId
ID d’activité de l’événement ou NULL pour utiliser la valeur par défaut.
[in, optional] pRelatedActivityId
ID d’activité associé pour l’événement ou NULL pour aucun ID d’activité associé.
[in, optional] __VA_ARGS__
Jusqu’à 99 paramètres supplémentaires pour configurer ou ajouter des champs à l’événement. Chaque paramètre doit être l’une des macros wrapper TraceLogging, telles que TraceLoggingLevel, TraceLoggingKeyword ou TraceLoggingValue.
Important
ProviderId, Level et Keyword sont les principaux moyens de filtrage des événements. D’autres types de filtrage sont possibles, mais ont une surcharge beaucoup plus élevée. Affectez toujours un niveau différent de zéro et mot clé à chaque événement.
Valeur de retour
None
Remarques
Chaque appel de la macro TraceLoggingWriteActivity s’étend au code nécessaire pour écrire un événement dans ETW via le handle de fournisseur spécifié.
- TraceLoggingWriteActivity vérifie si le fournisseur spécifié est inscrit. Si le fournisseur n’est pas inscrit, TraceLoggingWriteActivity ne fait rien.
- TraceLoggingWriteActivity vérifie si un consommateur écoute l’événement, comme si en appelant TraceLoggingProviderEnabled. Si aucun consommateur n’écoute l’événement, TraceLoggingWriteActivity ne fait rien.
- Sinon, TraceLoggingWriteActivity évalue les expressions runtime spécifiées dans les arguments, enregistre les résultats, ajoute les données nécessaires dans un événement et appelle EventWriteTransfer pour envoyer l’événement à ETW.
L’événement généré sera construit comme suit :
- L’ID du fournisseur, le nom du fournisseur et le groupe de fournisseurs de l’événement proviennent du paramètre hProvider .
- Le nom de l’événement provient du paramètre eventName .
- L’ID d’activité de l’événement provient du paramètre pActivityId . Si pActivityId a la valeur NULL, les événements en mode utilisateur utilisent l’ID d’activité implicite du thread et les événements en mode noyau utilisent GUID_NULL.
- L’ID d’activité associé de l’événement provient du paramètre pRelatedActivityId . Si pRelatedActivityId a la valeur NULL, l’événement n’aura pas d’ID d’activité associé.
- Le niveau de l’événement provient de l’argument TraceLoggingLevel . Si aucun argument TraceLoggingLevel n’est présent, le niveau de l’événement est 5 (WINEVENT_LEVEL_VERBOSE). Si plusieurs arguments TraceLoggingLevel sont présents, le dernier argument est utilisé. Pour activer le filtrage effectif des événements, affectez toujours un niveau significatif autre que zéro à chaque événement.
- La mot clé de l’événement provient de l’argument TraceLoggingKeyword. Si aucun argument TraceLoggingKeyword n’est présent, la mot clé de l’événement est 0 (NONE). Si plusieurs arguments TraceLoggingKeyword sont présents, les valeurs sont OR’ed ensemble. Pour activer le filtrage d’événements effectif, affectez toujours une mot clé significative autre que zéro à chaque événement.
- D’autres attributs d’événement peuvent être définis par des arguments tels que TraceLoggingOpcode, TraceLoggingDescription, TraceLoggingEventTag ou TraceLoggingChannel.
- Les champs d’événement peuvent être regroupés à l’aide de TraceLoggingStruct.
- Les champs d’événements sont ajoutés par des arguments de champ tels que TraceLoggingValue, TraceLoggingInt32, TraceLoggingHResult, TraceLoggingString, etc. Pour plus d’informations, consultez Macros du wrapper TraceLogging .
Par exemple :
TraceLoggingWriteActivity(
g_hProvider,
"MyEvent1",
&myActivityGuid,
NULL, // no related activity ID
TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
TraceLoggingKeyword(MyNetworkingKeyword), // Provider-defined categories
TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.
Un appel de TraceLoggingWriteActivity(hProvider, "EventName", aid, rid, args...) peut être considéré comme un développement au code comme suit :
if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
static const metadata = { GetMetadataFromArgs(args...) };
EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
EventWriteTransfer(etwHandle, metadata.desc, aid, rid, N, data);
}
Notes
Chaque macro TraceLoggingWriteActivity vérifie automatiquement TraceLoggingProviderEnabled afin que l’événement ne soit écrit que si un consommateur écoute les événements du fournisseur. Par conséquent, il n’est généralement pas nécessaire d’appeler directement TraceLoggingProviderEnabled. Toutes les expressions runtime dans args... seront évaluées si et uniquement si l’événement est activé. Les expressions runtime ne seront pas évaluées plusieurs fois.
Si vous générez des événements complexes, vous pouvez obtenir une erreur du compilateur indiquant que la ligne est trop longue ou que le compilateur n’a plus d’espace de tas. Cela se produit lorsque la macro TraceLoggingWriteActivity se développe sur une ligne plus longue que celle qui peut être prise en charge par le compilateur. Si cela se produit, vous devez simplifier votre événement.
La macro TraceLoggingWriteActivity utilise un tableau de EVENT_DATA_DESCRIPTOR pour transférer des données vers ETW. Le nombre maximal de descripteurs acceptés par ETW est de 128. Étant donné que chaque paramètre peut nécessiter l’utilisation de 0, 1 ou 2 descripteurs, il est possible d’atteindre la limite de descripteur de données (128) avant d’atteindre la limite d’argument (99).
Important
Essayez d’éviter les événements volumineux. ETW est principalement conçu pour gérer les petits événements. TraceLoggingWriteActivity supprime silencieusement tout événement trop important. La taille de l’événement est basée sur le total des en-têtes de l’événement (ajoutés par le runtime ETW), des métadonnées (c’est-à-dire le nom du fournisseur, le nom de l’événement, les noms de champs, les types de champs) et les données (valeurs de champ). Si la taille totale de l’événement est supérieure à 65535 ou si la session consommateur utilise une taille de mémoire tampon inférieure à la taille de l’événement, l’événement n’est pas enregistré.
Un appel à TraceLoggingWrite est identique à un appel à TraceLoggingWriteActivity avec NULL pour les paramètres pActivityId et pRelatedActivityId . Utilisez TraceLoggingWriteActivity si vous devez spécifier des ID d’activité pour un événement.
Consultez EventWriteTransfer pour plus d’informations sur la sémantique des paramètres ActivityId et RelatedActivityId .
Pour plus d’informations sur l’écriture d’activités dans ETW, consultez EventActivityIdControl .
Consultez TraceLoggingActivity pour les classes C++ qui vous aident à gérer les activités TRACELogging ETW.
Configuration requise
| 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 | traceloggingprovider.h |
| Bibliothèque | Advapi32.lib |