Macro TraceLoggingCustom (traceloggingprovider.h)

Artículo
08/26/2023

Macro contenedora TraceLogging que agrega un campo empaquetado mediante un serializador personalizado al evento.

La mayoría de los eventos traceLogging no necesitan usar un serializador personalizado y no deben usar TraceLoggingCustom.

Sintaxis

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

Parámetros

[in] pValue

Puntero a la carga del campo, serializada en tiempo de ejecución por un serializador de la familia de protocolos especificada.

[in] cbValue

Tamaño, en bytes, de la carga del campo, serializada en tiempo de ejecución por un serializador de la familia de protocolos especificada.

[in] protocol

Una familia de protocolos, que puede ser un valor definido por Microsoft de 0 a 4 o un valor definido por el usuario de 5 a 31. Los valores definidos por Microsoft se definen mediante macros que comienzan por TRACELOGGING_PROTOCOL_.

[in] bSchema

Lista separada por comas de valores de bytes que contienen la información necesaria para descodificar la carga (es decir, el esquema), en un formato definido por protocolo. Los valores de esta lista deben ser constantes en tiempo de compilación. Ejemplo: (0x12, 0x23, 0x34)

[in] cbSchema

Número de valores de bytes proporcionados en bSchema. Este valor debe ser una constante en tiempo de compilación.

[in, optional] __VA_ARGS__

Parámetros de nombre, descripción y etiquetas opcionales para la definición de campo.

TraceLoggingCustom se puede especificar con 5, 6, 7 o 8 parámetros. Si no se especifica un parámetro, se usará un valor predeterminado. Por ejemplo, TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema) es equivalente a TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema, "&x.data", "", 0).

[in, optional] name

Nombre que se va a usar para el campo de evento. Si se proporciona, el parámetro name debe ser un literal de cadena (no una variable) y no debe contener ningún carácter '\0'. Si no se proporciona, el nombre del campo de evento se basará en pValue.
[in, optional] description

Descripción del valor del campo de evento. Si se proporciona, el parámetro description debe ser un literal de cadena y se incluirá en la PDB.
[in, optional] tags

Valor entero constante en tiempo de compilación. Los 28 bits bajos del valor se incluirán en los metadatos del campo. La semántica de este valor se define mediante el consumidor de eventos. Durante el procesamiento de eventos, este valor se puede recuperar del campo Etiquetas de EVENT_PROPERTY_INFO .

Valor devuelto

None

Observaciones

TraceLoggingCustom(pValue, cbValue, protocol, (schema...), cbSchema, ...) se puede usar como parámetro para una invocación de una macro TraceLoggingWrite . Cada parámetro TraceLoggingCustom agrega un campo serializado personalizado al evento. La mayoría de los eventos traceLogging no usan serializadores personalizados y no deben usar TraceLoggingCustom. Los descodificadores ETW de uso general no admiten campos que usan serialización personalizada y normalmente tratarán los campos como TDH_INTYPE_BINARY.

Los descodificadores deben tener acceso a los campos serializados TraceLoggingCustom mediante las API de TDH. La estructura TRACE_EVENT_INFO devuelta por TdhGetEventInformation contendrá dos estructuras de EVENT_PROPERTY_INFO relacionadas con un campo TraceLoggingCustom registrado. Se correlacionan de la manera típica con los datos encontrados en el blob UserData de la EVENT_RECORD para un campo binario (TDH_INTYPE_BINARY).

La primera de las dos estructuras EVENT_PROPERTY_INFO es la propiedad "Length" que describe la longitud de la carga serializada (es decir, cbValue).
El segundo es la propiedad que hace referencia a la carga del usuario (pbValue). La segunda propiedad tendrá el conjunto PropertyParamLength (en referencia a la propiedad "Length") y PropertyHasCustomSchema.

Los descodificadores deben reconocer que se ha establecido PropertyHasCustomSchema y consultar el miembro customSchemaType del EVENT_PROPERTY_INFO para customSchemaOffset, que es el desplazamiento en el TRACE_EVENT_INFORMATION donde se encuentran el tipo de protocolo y los metadatos del protocolo. Allí, pueden encontrar los metadatos que pasaron con un formato de (pseudostruct):

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

Los descodificadores existentes que no realizan estos pasos adicionales para reconocer la marca PropertyHasCustomSchema y, en su lugar, hacen referencia a la parte nonStructType de la unión EVENT_PROPERTY_INFO para descodificar el evento tratarán sin problemas la carga como si fuera TDH_INTYPE_BINARY.

Ejemplos

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

Requisitos


Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	traceloggingprovider.h

Consulte también

TraceLoggingWrite

Macros contenedoras de TraceLogging

Share via