Compartir a través de

Macro TraceLoggingWrite (traceloggingprovider.h)

  • Artículo

Emite un evento TraceLogging.

Sintaxis

void TraceLoggingWrite(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  __VA_ARGS__
);

Parámetros

[in] hProvider

Identificador del proveedor TraceLogging que se va a usar para escribir el evento.

[in] eventName

Nombre corto y único que se usará para identificar el evento. Debe ser un literal de cadena y no una variable. No puede tener caracteres incrustados '\0' .

[in, optional] __VA_ARGS__

Hasta 99 parámetros adicionales para configurar o agregar campos al evento. Cada parámetro debe ser una de las macros contenedoras de seguimiento, como TraceLoggingLevel, TraceLoggingKeyword o TraceLoggingValue.

Importante

ProviderId, Level y Keyword son los medios principales para filtrar eventos. Otros tipos de filtrado son posibles, pero tienen una sobrecarga mucho mayor. Asigne siempre un nivel distinto de cero y una palabra clave a todos los eventos.

Valor devuelto

None

Observaciones

Cada invocación de la macro TraceLoggingWrite se expande al código necesario para escribir un evento en ETW a través del identificador de proveedor especificado.

  • TraceLoggingWrite comprueba si el proveedor especificado está registrado. Si el proveedor no está registrado, TraceLoggingWrite no hace nada.
  • TraceLoggingWrite comprueba si algún consumidor está escuchando el evento, como si llamara a TraceLoggingProviderEnabled. Si ningún consumidor escucha el evento, TraceLoggingWrite no hace nada.
  • De lo contrario, TraceLoggingWrite evalúa las expresiones en tiempo de ejecución especificadas en los argumentos, guarda los resultados, empaqueta los datos necesarios en un evento y llama a EventWriteTransfer para enviar el evento a ETW.

El evento generado se construirá de la siguiente manera:

  • El identificador de proveedor, el nombre del proveedor y el grupo de proveedores del evento provendrán del parámetro hProvider .
  • El nombre del evento provendrá del parámetro eventName .
  • En modo de usuario, el identificador de actividad del evento provendrá del identificador de actividad implícito del subproceso. En el modo kernel, el identificador de actividad del evento se GUID_NULL.
  • El evento no tendrá un identificador de actividad relacionado.
  • El nivel del evento provendrá del argumento TraceLoggingLevel . Si no hay ningún argumento TraceLoggingLevel presente, el nivel del evento será 5 (WINEVENT_LEVEL_VERBOSE). Si hay más de un argumento TraceLoggingLevel presente, se usará el último argumento. Para habilitar el filtrado de eventos efectivo, asigne siempre un nivel distinto de cero significativo a cada evento.
  • La palabra clave del evento provendrá del argumento TraceLoggingKeyword . Si no hay ningún argumento TraceLoggingKeyword presente, la palabra clave del evento será 0 (NONE). Si hay más de un argumento TraceLoggingKeyword presente, los valores se combinarán juntos. Para habilitar el filtrado de eventos efectivo, asigne siempre una palabra clave significativa distinta de cero a cada evento.
  • Otros atributos de evento se pueden establecer mediante argumentos como TraceLoggingOpcode, TraceLoggingDescription, TraceLoggingEventTag o TraceLoggingChannel.
  • Los campos de evento se pueden agrupar mediante TraceLoggingStruct.
  • Los campos de evento se agregan mediante argumentos de campo como TraceLoggingValue, TraceLoggingInt32, TraceLoggingHResult, TraceLoggingString, etc. Consulte Macros contenedoras de seguimiento para obtener más información.

Por ejemplo:

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.

Se puede considerar una invocación de TraceLoggingWrite(hProvider, "EventName", args...) como expandirse al código como el siguiente:

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);
}

Nota:

Cada macro TraceLoggingWrite comprueba automáticamente TraceLoggingProviderEnabled , por lo que el evento solo se escribirá si un consumidor escucha eventos del proveedor. Como resultado, normalmente no es necesario llamar directamente a TraceLoggingProviderEnabled. Todas las expresiones en tiempo de ejecución de args... se evaluarán si y solo si el evento está habilitado. Las expresiones en tiempo de ejecución no se evaluarán más de una vez.

Si genera eventos complejos, puede obtener un error del compilador que indica que la línea es demasiado larga o que el compilador está fuera del espacio del montón. Esto ocurre cuando la macro TraceLoggingWrite se expande a una línea más larga de la que puede admitir el compilador. Si esto sucede, deberá simplificar el evento.

La macro TraceLoggingWrite usa una matriz de EVENT_DATA_DESCRIPTOR para transferir datos a ETW. El número máximo de descriptores aceptados por ETW es 128. Dado que cada parámetro puede requerir el uso de 0, 1 o 2 descriptores, es posible alcanzar el límite de descriptores de datos (128) antes de alcanzar el límite de argumentos (99).

Importante

Intente evitar eventos grandes. ETW está diseñado principalmente para controlar eventos pequeños. TraceLoggingWrite quitará silenciosamente cualquier evento que sea demasiado grande. El tamaño del evento se basa en el total de los encabezados del evento (agregados por el tiempo de ejecución de ETW), los metadatos (es decir, el nombre del proveedor, el nombre de evento, los nombres de campo, los tipos de campo) y los datos (valores de campo). Si el tamaño total del evento es mayor que 65535 o si la sesión del consumidor usa un tamaño de búfer menor que el tamaño del evento, el evento no se registrará.

Una llamada a TraceLoggingWrite es la misma que una llamada a TraceLoggingWriteActivity con NULL para los parámetros pActivityId y pRelatedActivityId . Use TraceLoggingWriteActivity si necesita especificar identificadores de actividad para un evento.

Ejemplos

#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;
}

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
Library Advapi32.lib

Consulte también

EventWriteTransfer

TraceLoggingWriteActivity

Macros contenedoras de seguimiento