Macro TraceLoggingWriteActivity (traceloggingprovider.h)
Emite un evento TraceLogging con identificadores de actividad especificados.
Sintaxis
void TraceLoggingWriteActivity(
[in] hProvider,
[in] eventName,
[in, optional] pActivityId,
[in, optional] pRelatedActivityId,
[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] pActivityId
Identificador de actividad del evento o NULL para usar el valor predeterminado.
[in, optional] pRelatedActivityId
Identificador de actividad relacionado para el evento o NULL para ningún identificador de actividad relacionado.
[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 TraceLoggingWriteActivity se expande al código necesario para escribir un evento en ETW a través del identificador de proveedor especificado.
- TraceLoggingWriteActivity comprueba si el proveedor especificado está registrado. Si el proveedor no está registrado, TraceLoggingWriteActivity no hace nada.
- TraceLoggingWriteActivity comprueba si algún consumidor está escuchando el evento, como si llamara a TraceLoggingProviderEnabled. Si ningún consumidor escucha el evento, TraceLoggingWriteActivity no hace nada.
- De lo contrario, TraceLoggingWriteActivity 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 .
- El identificador de actividad del evento provendrá del parámetro pActivityId . Si pActivityId es NULL, los eventos en modo de usuario usarán el identificador de actividad implícito del subproceso y los eventos en modo kernel usarán GUID_NULL.
- El identificador de actividad relacionado del evento provendrá del parámetro pRelatedActivityId . Si pRelatedActivityId es 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:
TraceLoggingWriteActivity(
g_hProvider,
"MyEvent1",
&myActivityGuid,
NULL, // no related activity ID
TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
TraceLoggingKeyword(MyNetworkingKeyword), // Provider-defined categories
TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.
Se puede considerar una invocación de TraceLoggingWriteActivity(hProvider, "EventName", aid, rid, 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, aid, rid, N, data);
}
Nota:
Cada macro TraceLoggingWriteActivity 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 TraceLoggingWriteActivity se expande a una línea más larga de la que el compilador puede admitir. Si esto sucede, deberá simplificar el evento.
La macro TraceLoggingWriteActivity 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. TraceLoggingWriteActivity 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.
Consulte EventWriteTransfer para obtener información sobre la semántica de los parámetros ActivityId y RelatedActivityId .
Consulte EventActivityIdControl para obtener información sobre cómo escribir actividades en ETW.
Consulte TraceLoggingActivity para las clases de C++ que ayudan a administrar las actividades etW de TraceLogging.
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 |