Función EventWriteEx (evntprov.h)
Escribe un evento ETW con un identificador de actividad, un identificador de actividad relacionado opcional, filtros de sesión y opciones especiales.
Sintaxis
ULONG EVNTAPI EventWriteEx(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG64 Filter,
[in] ULONG Flags,
[in, optional] LPCGUID ActivityId,
[in, optional] LPCGUID RelatedActivityId,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
Parámetros
[in] RegHandle
Identificador de registro del proveedor. El identificador procede de EventRegister. El evento generado usará el ProviderId asociado al identificador.
[in] EventDescriptor
EVENT_DESCRIPTOR con información de eventos (metadatos), incluidos el identificador, la versión, el nivel, la palabra clave, el canal, el código de operación y la tarea.
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 cada evento.
[in] Filter
Valor de máscara de bits de 64 bits. Cada bit establecido indica que este evento debe excluirse de una sesión de seguimiento determinada.
El parámetro Filter se usa con proveedores de eventos que realizan el filtrado de eventos personalizado en función de FilterData de EnableCallback.
Establezca Filtro en cero si no admite filtros de eventos personalizados o si el evento se debe escribir en todas las sesiones de seguimiento. De lo contrario, establezca Filter en el or bit a bit de los identificadores de las sesiones que NO deben recibir el evento.
[in] Flags
Establezca Marcas en cero para el control de eventos normal.
Establezca Marcas en una combinación de valores de EVENT_WRITE_FLAG para el control de eventos especiales.
EVENT_WRITE_FLAG_INPRIVATE (0x2)
Indica que este evento debe excluirse de cualquier registrador que haya establecido la opción EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE .
[in, optional] ActivityId
Puntero opcional a un identificador de actividad de 128 bits para este evento. Si no es NULL, EventWriteEx usará el valor especificado para el identificador de actividad del evento. Si es NULL, EventWriteEx usará el identificador de actividad del subproceso actual.
Las herramientas de procesamiento de seguimiento pueden usar el identificador de actividad del evento para organizar los eventos en grupos denominados actividades. Para obtener más información sobre el identificador de actividad, consulte EventActivityIdControl.
[in, optional] RelatedActivityId
Puntero opcional a un identificador de actividad de 128 bits que es el elemento primario de la actividad de este evento. Si no es NULL, EventWriteEx usará el valor especificado para el identificador de actividad relacionado del evento. Si es NULL, el evento no tendrá un identificador de actividad relacionado. Normalmente, el identificador de actividad relacionado se establece en el evento START de la actividad (el primer evento de la actividad, registrado con Opcode = START).
Las herramientas de procesamiento de seguimiento pueden usar el identificador de actividad relacionado del evento para determinar la relación entre las actividades, por ejemplo, la actividad relacionada es el elemento primario de la actividad recién iniciada. Para obtener más información sobre el identificador de actividad relacionado, consulte EventActivityIdControl.
[in] UserDataCount
Número de estructuras de EVENT_DATA_DESCRIPTOR en UserData. El número máximo es 128.
[in, optional] UserData
Matriz de userDataCountEVENT_DATA_DESCRIPTOR estructuras que describen los datos que se van a incluir en el evento. UserData puede ser NULL si UserDataCount es cero.
Cada EVENT_DATA_DESCRIPTOR describe un bloque de memoria que se va a incluir en el evento . Los bloques especificados se concatenan en orden sin relleno ni alineación para formar el contenido del evento. Si usa la descodificación basada en manifiestos, el contenido del evento debe coincidir con el diseño especificado en la plantilla asociada al evento en el manifiesto.
Valor devuelto
Devuelve ERROR_SUCCESS si se ejecuta correctamente o un código de error. Entre los posibles códigos de error se incluyen los siguientes:
- ERROR_INVALID_PARAMETER: uno o varios de los parámetros no son válidos.
- ERROR_INVALID_HANDLE: el identificador de registro del proveedor no es válido.
- ERROR_ARITHMETIC_OVERFLOW: el tamaño del evento es mayor que el máximo permitido (64 KB - encabezado).
- ERROR_MORE_DATA: el tamaño del búfer de sesión es demasiado pequeño para el evento.
- ERROR_NOT_ENOUGH_MEMORY: se produce cuando los búferes rellenados intentan vaciar el disco, pero las E/S de disco no se producen lo suficientemente rápido. Esto sucede cuando el disco es lento y el tráfico de eventos es pesado. Finalmente, no hay más búferes libres (vacíos) y se quita el evento.
- STATUS_LOG_FILE_FULL: el archivo de reproducción en tiempo real está lleno. Los eventos no se registran en la sesión hasta que un consumidor en tiempo real consume los eventos del archivo de reproducción.
El código de error está pensado principalmente para su uso en escenarios de depuración y diagnóstico. La mayoría del código de producción debe seguir ejecutándose y seguir notificando eventos incluso si no se pudo escribir un evento ETW, por lo que las compilaciones de versión normalmente deben omitir el código de error.
Comentarios
La mayoría de los proveedores de eventos no llamarán directamente a EventWriteEx . En su lugar, la mayoría de los proveedores de eventos se implementan mediante un marco ETW que ajusta las llamadas a EventRegister, EventWriteEx y EventUnregister. Por ejemplo, puede escribir un manifiesto de evento y, a continuación, usar el compilador de mensajes para generar código de C/C++ para los eventos, o puede usar TraceLogging para evitar la necesidad de un manifiesto.
EventWriteEx enrutará el evento a las sesiones de seguimiento adecuadas en función del ProviderId (determinado por regHandle), Level, Keyword y otras características de evento. Si no hay sesiones de seguimiento que graben este evento, esta función no hará nada y devolverá ERROR_SUCCESS.
Para reducir el impacto en el rendimiento de los eventos que no se registran en ninguna sesión de seguimiento, puede llamar a EventEnabled para determinar si alguna sesión de seguimiento está grabando el evento antes de preparar los datos y llamar a EventWriteEx.
Un proveedor puede definir filtros que una sesión usa para filtrar los eventos en función de los datos de eventos. Los filtros principales se basan en el nivel y las palabras clave. Los proveedores de eventos pueden admitir filtros más complejos. El proveedor de eventos puede recibir información de filtro del parámetro FilterData de EnableCallback. El proveedor puede evaluar el filtro y usar el parámetro Filter de EventWriteEx para indicar que determinadas sesiones de seguimiento no pasaron el filtro y, por tanto, no deberían recibir el evento.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 7 [aplicaciones de escritorio | Aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2008 R2 [aplicaciones de escritorio | Aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | evntprov.h |
| Library | Advapi32.lib |
| Archivo DLL | Advapi32.dll |