TraceLoggingCustom-Makro (traceloggingprovider.h)

Artikel
08/26/2023

TraceLogging-Wrappermakro , das dem Ereignis ein Feld hinzufügt, das mithilfe eines benutzerdefinierten Serialisierungsprogramms gepackt wurde.

Die meisten TraceLogging-Ereignisse müssen kein benutzerdefiniertes Serialisierungsprogramm verwenden und sollten nicht TraceLoggingCustom verwenden.

Syntax

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

Parameter

[in] pValue

Ein Zeiger auf die Nutzlast des Felds, der zur Laufzeit von einem Serialisierer aus der angegebenen Protokollfamilie serialisiert wird.

[in] cbValue

Die Größe der Nutzlast des Felds in Bytes, die zur Laufzeit von einem Serialisierer aus der angegebenen Protokollfamilie serialisiert wird.

[in] protocol

Eine Protokollfamilie, die ein von Microsoft definierter Wert von 0-4 oder ein benutzerdefinierter Wert von 5-31 sein kann. Die von Microsoft definierten Werte werden durch Makros definiert, die mit TRACELOGGING_PROTOCOL_beginnen.

[in] bSchema

Eine durch Trennzeichen getrennte Liste von Bytewerten, die die Informationen enthalten, die zum Decodieren der Nutzlast (d. h. des Schemas) in einem protokolldefinierten Format erforderlich sind. Die Werte in dieser Liste müssen Kompilierzeitkonstante sein. Beispiel: (0x12, 0x23, 0x34)

[in] cbSchema

Die Anzahl der in bSchema bereitgestellten Bytewerte. Dieser Wert muss eine Kompilierzeitkonstante sein.

[in, optional] __VA_ARGS__

Optionale Namen-, Beschreibungs- und Tagsparameter für die Felddefinition.

TraceLoggingCustom kann mit 5, 6, 7 oder 8 Parametern angegeben werden. Wenn kein Parameter angegeben wird, wird ein Standardwert verwendet. TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema) entspricht beispielsweise TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema, "&x.data", "", 0).

[in, optional] name

Der Name, der für das Ereignisfeld verwendet werden soll. Falls angegeben, muss der Name-Parameter ein Zeichenfolgenliteral (keine Variable) sein und darf keine "\0"-Zeichen enthalten. Wenn nicht angegeben, basiert der Name des Ereignisfelds auf pValue.
[in, optional] description

Die Beschreibung des Werts des Ereignisfelds. Falls angegeben, muss der Beschreibungsparameter ein Zeichenfolgenliteral sein und wird im PDB enthalten sein.
[in, optional] tags

Ein ganzzahliger Wert für die Kompilierzeitkonstante. Die niedrigen 28 Bit des Werts werden in den Metadaten des Felds enthalten. Die Semantik dieses Werts wird vom Ereignis consumer definiert. Während der Ereignisverarbeitung kann dieser Wert aus dem Feld EVENT_PROPERTY_INFO Tags abgerufen werden.

Rückgabewert

Keine

Bemerkungen

TraceLoggingCustom(pValue, cbValue, protocol, (schema...), cbSchema, ...) kann als Parameter für einen Aufruf eines TraceLoggingWrite-Makros verwendet werden. Jeder TraceLoggingCustom-Parameter fügt dem Ereignis ein benutzerdefiniertes serialisiertes Feld hinzu. Die meisten TraceLogging-Ereignisse verwenden keine benutzerdefinierten Serialisierer und sollten nicht TraceLoggingCustom verwenden. Universelle ETW-Decoder unterstützen keine Felder, die benutzerdefinierte Serialisierung verwenden, und behandeln die Felder in der Regel als TDH_INTYPE_BINARY.

Decoder sollten mithilfe der TDH-APIs auf serialisierte TraceLoggingCustom-Felder zugreifen. Die von TdhGetEventInformation zurückgegebene TRACE_EVENT_INFO-Struktur enthält zwei EVENT_PROPERTY_INFO Strukturen, die sich auf ein protokolliertes TraceLoggingCustom-Feld beziehen. Diese korrelieren in der typischen Weise mit den Daten im UserData-Blob des EVENT_RECORD für ein Binärfeld (TDH_INTYPE_BINARY).

Die erste der beiden EVENT_PROPERTY_INFO Strukturen ist die "Length"-Eigenschaft, die die Länge der serialisierten Nutzlast (d. h. cbValue) beschreibt.
Die zweite ist die Eigenschaft, die auf die Nutzlast des Benutzers (pbValue) verweist. Für die zweite Eigenschaft sind PropertyParamLength (in Bezug auf die Eigenschaft "Length") und PropertyHasCustomSchema festgelegt.

Decoder sollten erkennen, dass PropertyHasCustomSchema festgelegt wurde, und das customSchemaType-Element des EVENT_PROPERTY_INFO für customSchemaOffset konsultieren, das den Offset im TRACE_EVENT_INFORMATION darstellt, in dem sich der Protokolltyp und die Protokollmetadaten befinden. Dort können sie die Metadaten finden, die sie im Format (Pseudostruktur) übergeben haben:

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

Vorhandene Decoder, die diese zusätzlichen Schritte nicht ausführen, um das PropertyHasCustomSchema-Flag zu erkennen, und stattdessen auf den NonStructType-Teil der EVENT_PROPERTY_INFO Union verweisen, um das Ereignis zu decodieren, behandeln die Nutzlast nahtlos so, als wäre sie TDH_INTYPE_BINARY.

Beispiele

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

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	traceloggingprovider.h

Weitere Informationen

TraceLoggingWrite

TraceLogging-Wrappermakros

Share via