Función TraceEventInstance (evntrace.h)

Artículo
03/11/2023

Un proveedor de eventos basado en RegisterTraceGuids ("clásico") usa la función TraceEventInstance para enviar un evento estructurado a una sesión de seguimiento de eventos con un identificador de instancia.

El evento usa un identificador de instancia para asociar el evento a una transacción. Esta función también se puede usar para realizar un seguimiento de las relaciones jerárquicas entre eventos relacionados.

Sintaxis

ULONG WMIAPI TraceEventInstance(
  [in] TRACEHANDLE            TraceHandle,
  [in] PEVENT_INSTANCE_HEADER EventTrace,
  [in] PEVENT_INSTANCE_INFO   InstInfo,
  [in] PEVENT_INSTANCE_INFO   ParentInstInfo
);

Parámetros

[in] TraceHandle

Controle la sesión de seguimiento de eventos que registra la instancia de evento. El proveedor obtiene el identificador cuando llama a la función GetTraceLoggerHandle en su implementación de ControlCallback .

[in] EventTrace

Puntero a una estructura de EVENT_INSTANCE_HEADER . Opcionalmente, los datos específicos del evento se anexan a la estructura. El evento más grande que puede registrar es 64K. Debe especificar valores para los siguientes miembros de la estructura EVENT_INSTANCE_HEADER .

Tamaño
Marcas
RegHandle

En función de la complejidad de la información que proporciona el proveedor, también debe considerar la posibilidad de especificar valores para los siguientes miembros.

Class.Type
Class.Level

Para realizar un seguimiento de las relaciones jerárquicas entre eventos relacionados, establezca también el miembro ParentRegHandle .

[in] InstInfo

Puntero a una estructura de EVENT_INSTANCE_INFO , que contiene el identificador de registro de esta clase de seguimiento de eventos y el identificador de instancia. Use la función CreateTraceInstanceId para inicializar la estructura.

[in] ParentInstInfo

Puntero a una estructura de EVENT_INSTANCE_INFO , que contiene el identificador de registro de la clase de seguimiento de eventos principal y su identificador de instancia. Use la función CreateTraceInstanceId para inicializar la estructura. Establezca en NULL si no está trazando una relación jerárquica.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto es uno de los códigos de error del sistema. A continuación se muestran algunos errores comunes y sus causas.

ERROR_INVALID_FLAGS

El miembro Flags del EVENT_INSTANCE_HEADER no contiene WNODE_FLAG_TRACED_GUID.
ERROR_OUTOFMEMORY

No había memoria suficiente para completar la llamada de función. Las causas de este código de error se describen en la siguiente sección Comentarios.
ERROR_INVALID_PARAMETER

Una de las siguientes condiciones se cumple:
- EventTrace es NULL.
- pInstInfo es NULL.
- Los miembros de pInstInfo son NULL.
- TraceHandle es NULL.
- El miembro Size del EVENT_INSTANCE_HEADER es incorrecto.
ERROR_INVALID_HANDLE

TraceHandle no es válido o especifica el identificador de sesión del registrador de kernel nt.
ERROR_NOT_ENOUGH_MEMORY

La sesión se quedó sin búferes libres donde escribir. Esto puede ocurrir cuando las tasas de eventos son elevadas porque el subsistema del disco se sobrecarga o el número de búferes es demasiado pequeño. En lugar de bloquear hasta que más búferes estén disponibles, TraceEvent descarta el evento.

Windows 2000 y Windows XP: No se admite.
ERROR_OUTOFMEMORY

El evento se descarta porque, aunque el grupo de búferes no ha alcanzado su tamaño máximo, no hay suficiente memoria disponible para asignar un búfer adicional y no hay ningún búfer disponible para recibir el evento.
ERROR_MORE_DATA

Los datos de un único evento no pueden abarcar varios búferes. Un evento de seguimiento se limita al tamaño del búfer de la sesión de seguimiento de eventos menos el tamaño de la estructura de EVENT_INSTANCE_HEADER .

Comentarios

Los proveedores ETW basados en MOF llaman a esta función.

Nota

La mayoría de los desarrolladores no llamarán a esta función. Esta API admite ETW basado en MOF, pero ETW basado en MOF está en desuso en favor de ETW basado en manifiestos. Además, la mayoría de los proveedores basados en MOF usan funciones de contenedor generadas por MC.exe en lugar de llamar directamente a las API de ETW.

Antes de que el proveedor pueda llamar a esta función, el proveedor

Debe llamar a la función RegisterTraceGuids para registrarse y la clase de seguimiento de eventos.
Debe llamar a la función CreateTraceInstanceId para crear un identificador de instancia para la clase de seguimiento de eventos registrada.
Debe estar habilitado. Un controlador llama a la función EnableTrace para habilitar un proveedor.

El evento se escribe en un archivo de registro, se envía a los consumidores de seguimiento de eventos en tiempo real o ambos. El miembro LogFileMode de la estructura EVENT_TRACE_PROPERTIES pasada a StartTrace define dónde se envía el evento.

Los eventos de seguimiento se escriben en el orden en que se producen.

Para realizar un seguimiento de eventos no relacionados, use la función TraceEvent .

Windows XP: No funciona correctamente.

Ejemplos

Para obtener un ejemplo de cómo generar conjuntos de eventos relacionados mediante CreateTraceInstanceId y TraceEventInstance, consulte Seguimiento de instancias de eventos.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	evntrace.h
Library	Advapi32.lib
Archivo DLL	Advapi32.dll