Macro TraceLoggingCustom (traceloggingprovider.h)

Articolo
08/26/2023

Macro wrapper TraceLogging che aggiunge un campo compresso utilizzando un serializzatore personalizzato all'evento.

La maggior parte degli eventi TraceLogging non deve usare un serializzatore personalizzato e non deve usare TraceLoggingCustom.

Sintassi

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

Parametri

[in] pValue

Puntatore al payload del campo, serializzato in fase di esecuzione da un serializzatore della famiglia di protocolli specificata.

[in] cbValue

Dimensioni, in byte, del payload del campo, serializzate in fase di esecuzione da un serializzatore della famiglia di protocolli specificata.

[in] protocol

Famiglia di protocolli, che può essere un valore definito da Microsoft da 0 a 4 o un valore definito dall'utente da 5 a 31. I valori definiti da Microsoft sono definiti dalle macro che iniziano con TRACELOGGING_PROTOCOL_.

[in] bSchema

Elenco delimitato da virgole di valori di byte che contengono le informazioni necessarie per decodificare il payload (ad esempio lo schema), in un formato definito dal protocollo. I valori in questo elenco devono essere costanti in fase di compilazione. Esempio: (0x12, 0x23, 0x34)

[in] cbSchema

Numero di valori di byte forniti in bSchema. Questo valore deve essere una costante in fase di compilazione.

[in, optional] __VA_ARGS__

Parametri di nome, descrizione e tag facoltativi per la definizione del campo.

TraceLoggingCustom può essere specificato con 5, 6, 7 o 8 parametri. Se non viene specificato un parametro, verrà utilizzato un valore predefinito. Ad esempio, TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema) equivale a TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema, "&x.data", "", 0).

[in, optional] name

Nome da utilizzare per il campo dell'evento. Se specificato, il parametro name deve essere un valore letterale stringa (non una variabile) e non deve contenere caratteri '\0'. Se non specificato, il nome del campo evento sarà basato su pValue.
[in, optional] description

Descrizione del valore del campo evento. Se specificato, il parametro description deve essere un valore letterale stringa e verrà incluso nel PDB.
[in, optional] tags

Valore intero costante in fase di compilazione. I 28 bit bassi del valore verranno inclusi nei metadati del campo. La semantica di questo valore è definita dal consumer di eventi. Durante l'elaborazione degli eventi, questo valore può essere recuperato dal campo tag EVENT_PROPERTY_INFO .

Valore restituito

nessuno

Osservazioni

TraceLoggingCustom(pValue, cbValue, protocol, (schema...), cbSchema, ...) può essere usato come parametro per una chiamata di una macro TraceLoggingWrite . Ogni parametro TraceLoggingCustom aggiunge un campo serializzato personalizzato all'evento. La maggior parte degli eventi TraceLogging non usa serializzatori personalizzati e non deve usare TraceLoggingCustom. I decodificatori ETW per utilizzo generico non supportano campi che usano la serializzazione personalizzata e in genere considerano i campi come TDH_INTYPE_BINARY.

I decodificatori devono accedere ai campi serializzati TraceLoggingCustom usando le API TDH. La struttura TRACE_EVENT_INFO restituita da TdhGetEventInformation conterrà due strutture EVENT_PROPERTY_INFO correlate a un campo TraceLoggingCustom registrato. Questi elementi sono correlati in modo tipico con i dati trovati nel BLOB UserData del EVENT_RECORD per un campo binario (TDH_INTYPE_BINARY).

La prima delle due strutture EVENT_PROPERTY_INFO è la proprietà "Length" che descrive la lunghezza del payload serializzato ,ad esempio cbValue.
Il secondo è la proprietà che fa riferimento al payload dell'utente (pbValue). La seconda proprietà avrà PropertyParamLength (in riferimento alla proprietà "Length") e PropertyHasCustomSchema impostata.

I decodificatori devono riconoscere che PropertyHasCustomSchema è stato impostato e consultare il membro customSchemaType del EVENT_PROPERTY_INFO per CustomSchemaOffset, ovvero l'offset nel TRACE_EVENT_INFORMATION in cui si trovano il tipo di protocollo e i metadati del protocollo. Qui è possibile trovare i metadati passati con un formato (pseudo-struct):

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

I decodificatori esistenti che non eseguono questi passaggi aggiuntivi per riconoscere il flag PropertyHasCustomSchema e fanno invece riferimento alla parte nonStructType dell'unione EVENT_PROPERTY_INFO per decodificare l'evento tratterà facilmente il payload come se fosse TDH_INTYPE_BINARY.

Esempio

// 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

Requisiti


Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	traceloggingprovider.h

Vedi anche

TraceLoggingWrite

Macro wrapper TraceLogging

Condividi tramite