Macro TraceLoggingWrite (traceloggingprovider.h)

Article
08/26/2023

Émet un événement TraceLogging.

Syntaxe

void TraceLoggingWrite(
  [in]            hProvider,
  [in]            eventName,
  [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] __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 TraceLoggingWrite est étendu au code nécessaire pour écrire un événement dans ETW via le handle de fournisseur spécifié.

TraceLoggingWrite vérifie si le fournisseur spécifié est inscrit. Si le fournisseur n’est pas inscrit, TraceLoggingWrite ne fait rien.
TraceLoggingWrite vérifie si un consommateur écoute l’événement, comme en appelant TraceLoggingProviderEnabled. Si aucun consommateur n’écoute l’événement, TraceLoggingWrite ne fait rien.
Sinon, TraceLoggingWrite évalue les expressions d’exécution spécifiées dans les arguments, enregistre les résultats, emballe 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 .
En mode utilisateur, l’ID d’activité de l’événement provient de l’ID d’activité implicite du thread. En mode noyau, l’ID d’activité de l’événement est GUID_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 sera 5 (WINEVENT_LEVEL_VERBOSE). Si plusieurs arguments TraceLoggingLevel sont présents, le dernier argument est utilisé. Pour activer le filtrage d’événements efficace, 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 sera 0 (NONE). Si plusieurs arguments TraceLoggingKeyword sont présents, les valeurs sont OR’ed ensemble. Pour activer le filtrage d’événements efficace, affectez toujours une mot clé non nulle significative à 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énement 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 :

TraceLoggingWrite(
    g_hProvider,
    "MyEvent1",
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword),
    TraceLoggingString(operationName), // Adds an "operationName" field.
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

Un appel de TraceLoggingWrite(hProvider, "EventName", args...) peut être considéré comme un développement vers du code comme suit :

if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
    static const metadata = { GetMetadataFromArgs(args...) };
    EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
    EventWriteTransfer(etwHandle, metadata.desc, NULL, NULL, N, data);
}

Notes

Chaque macro TraceLoggingWrite 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 d’exécution dans args... seront évaluées si et uniquement si l’événement est activé. Les expressions runtime ne seront pas évaluées plus d’une 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 TraceLoggingWrite s’étend 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 TraceLoggingWrite 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. TraceLoggingWrite supprime silencieusement tout événement trop volumineux. 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.

Exemples

#include <windows.h> // or <wdm.h> for kernel-mode.
#include <winmeta.h> // For event level definitions.
#include <TraceLoggingProvider.h>

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider,  // Name of the provider handle
    "MyProvider", // Human-readable name of the provider
    // ETW Control GUID: {b3864c38-4273-58c5-545b-8b3608343471}
    (0xb3864c38,0x4273,0x58c5,0x54,0x5b,0x8b,0x36,0x08,0x34,0x34,0x71));

int main(int argc, char* argv[]) // or DriverEntry for kernel-mode.
{
    TraceLoggingRegister(g_hProvider);

    TraceLoggingWrite(
        g_hProvider,
        "MyEvent1",
        TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
        TraceLoggingKeyword(MyEventCategories), // Provider-defined categories
        TraceLoggingString(argv[0], "arg0"), // field name is "arg0"
        TraceLoggingInt32(argc)); // field name is implicitly "argc"

    TraceLoggingUnregister(g_hProvider);
    return 0;
}

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

Voir aussi

EventWriteTransfer

TraceLoggingWriteActivity

TraceLogging Wrapper Macros

Share via