Macro TraceLoggingCustom (traceloggingprovider.h)

Article
08/26/2023

Macro wrapper TraceLogging qui ajoute un champ qui a été emballé à l’événement à l’aide d’un sérialiseur personnalisé.

La plupart des événements TraceLogging n’ont pas besoin d’utiliser un sérialiseur personnalisé et ne doivent pas utiliser TraceLoggingCustom.

Syntaxe

void TraceLoggingCustom(
  [in]            pValue,
  [in]            cbValue,
  [in]            protocol,
  [in]            bSchema,
  [in]            cbSchema,
  [in, optional]  __VA_ARGS__
);

Paramètres

[in] pValue

Pointeur vers la charge utile du champ, sérialisé au moment de l’exécution par un sérialiseur de la famille de protocoles spécifiée.

[in] cbValue

Taille, en octets, de la charge utile du champ, sérialisée au moment de l’exécution par un sérialiseur de la famille de protocoles spécifiée.

[in] protocol

Famille de protocoles, qui peut être une valeur définie par Microsoft comprise entre 0 et 4 ou une valeur définie par l’utilisateur de 5 à 31. Les valeurs définies par Microsoft sont définies par des macros commençant par TRACELOGGING_PROTOCOL_.

[in] bSchema

Liste séparée par des virgules de valeurs d’octet qui contiennent les informations nécessaires pour décoder la charge utile (c’est-à-dire le schéma), dans un format défini par protocole. Les valeurs de cette liste doivent être constantes au moment de la compilation. Exemple : (0x12, 0x23, 0x34)

[in] cbSchema

Nombre de valeurs d’octet fournies dans bSchema. Cette valeur doit être une constante au moment de la compilation.

[in, optional] __VA_ARGS__

Paramètres de nom, de description et d’étiquettes facultatifs pour la définition de champ.

TraceLoggingCustom peut être spécifié avec 5, 6, 7 ou 8 paramètres. Si aucun paramètre n’est spécifié, une valeur par défaut est utilisée. Par exemple, TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema) équivaut à TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema, "&x.data", "", 0).

[in, optional] name

Nom à utiliser pour le champ d’événement. S’il est fourni, le paramètre name doit être un littéral de chaîne (et non une variable) et ne doit pas contenir de caractères « \0 ». S’il n’est pas fourni, le nom du champ d’événement sera basé sur pValue.
[in, optional] description

Description de la valeur du champ d’événement. S’il est fourni, le paramètre de description doit être un littéral de chaîne et sera inclus dans le PDB.
[in, optional] tags

Valeur entière constante au moment de la compilation. Les 28 bits faibles de la valeur seront inclus dans les métadonnées du champ. La sémantique de cette valeur est définie par le consommateur d’événements. Pendant le traitement des événements, cette valeur peut être récupérée à partir du champ Balises EVENT_PROPERTY_INFO .

Valeur de retour

None

Remarques

TraceLoggingCustom(pValue, cbValue, protocol, (schema...), cbSchema, ...) peut être utilisé comme paramètre pour l’appel d’une macro TraceLoggingWrite . Chaque paramètre TraceLoggingCustom ajoute un champ sérialisé personnalisé à l’événement. La plupart des événements TraceLogging n’utilisent pas de sérialiseurs personnalisés et ne doivent pas utiliser TraceLoggingCustom. Les décodeurs ETW à usage général ne prennent pas en charge les champs qui utilisent la sérialisation personnalisée et les traitent généralement comme des TDH_INTYPE_BINARY.

Les décodeurs doivent accéder aux champs sérialisés TraceLoggingCustom à l’aide des API TDH. La structure TRACE_EVENT_INFO retournée par TdhGetEventInformation contiendra deux structures EVENT_PROPERTY_INFO liées à un champ TraceLoggingCustom journalisé. Elles sont généralement corrélées avec les données trouvées dans l’objet blob UserData du EVENT_RECORD pour un champ binaire (TDH_INTYPE_BINARY).

La première des deux structures EVENT_PROPERTY_INFO est la propriété « Length » qui décrit la longueur de la charge utile sérialisée (par exemple, cbValue).
La deuxième est la propriété qui fait référence à la charge utile de l’utilisateur (pbValue). La deuxième propriété aura PropertyParamLength (en référence à la propriété « Length ») et PropertyHasCustomSchema définis.

Les décodeurs doivent reconnaître que PropertyHasCustomSchema a été défini et consulter le membre customSchemaType du EVENT_PROPERTY_INFO pour le CustomSchemaOffset, qui est le décalage dans le TRACE_EVENT_INFORMATION où se trouvent le type de protocole et les métadonnées de protocole. Là, ils peuvent trouver les métadonnées qu’ils ont transmises avec un format de (pseudo-struct) :

struct _CUSTOM_SCHEMA {
    UINT16 protocolType;
    UINT16 cbSchema;
    BYTE bSchema[cbSchema];
};

Les décodeurs existants qui n’effectuent pas ces étapes supplémentaires pour reconnaître l’indicateur PropertyHasCustomSchema et qui font plutôt référence à la partie nonStructType de l’union EVENT_PROPERTY_INFO pour décoder l’événement traiteront de manière transparente la charge utile comme si elle était TDH_INTYPE_BINARY.

Exemples

// Value generated at runtime by serializer:
BYTE rgValue[] = {...};

TraceLoggingWrite(
   g_hProvider,
   "MyEventName",
   TraceLoggingCustom(
      rgValue,
      sizeof(rgValue),
      TRACELOGGING_PROTOCOL_MYPROTOCOL,
      ( 0x0, 0x1, 0x2 ), // Generated at compile-time
      3,
      "MyCustomField"),
   TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
   TraceLoggingKeyword(MyEventCategories)); // Provider-defined categories

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

Voir aussi

TraceLoggingWrite

Macros du wrapper TraceLogging

Partager via