PEVENT_RECORD_CALLBACK función de devolución de llamada (evntrace.h)

Artículo
03/11/2023

Los consumidores implementan esta devolución de llamada para recibir eventos de una sesión de procesamiento de seguimiento.

El tipo PEVENT_RECORD_CALLBACK define un puntero a esta función de devolución de llamada. EventRecordCallback es un marcador de posición para el nombre de función definido por la aplicación.

Sintaxis

PEVENT_RECORD_CALLBACK PeventRecordCallback;

void PeventRecordCallback(
  [in] PEVENT_RECORD EventRecord
)
{...}

Parámetros

[in] EventRecord

Puntero a una estructura de EVENT_RECORD que contiene la información del evento.

Valor devuelto

Ninguno

Observaciones

Para especificar la función a la que ETW llama para entregar eventos, establezca los miembros EventRecordCallback, Context y ProcessTraceMode de la estructura EVENT_TRACE_LOGFILE que se pasa a la función OpenTrace .

Establezca EventRecordCallback en la dirección de la función de devolución de llamada.
Establezca Context en un valor que se debe incluir en el campo UserContext de cada EVENT_RECORD proporcionado a la devolución de llamada.
Establezca ProcessTraceMode en las marcas que se van a usar al procesar el seguimiento. Para usar EventRecordCallback, debe incluir PROCESS_TRACE_MODE_EVENT_RECORD en el valor ProcessTraceMode .

Nota

Si la función EventRecordCallback recibe datos garblemados de ProcessTrace, compruebe las marcas especificadas en el ProcessTraceMode campo de la EVENT_TRACE_LOGFILE estructura que se proporcionó a OpenTrace. EVENT_TRACE_LOGFILELos campos EventCallback y EventRecordCallback son miembros superpuestos de una unión. Si el ProcessTraceMode campo incluye la marca, ProcessTrace invocará la PROCESS_TRACE_MODE_EVENT_RECORD devolución de llamada mediante la firma de la función EventRecordCallback. De lo contrario, ProcessTrace invocará la devolución de llamada mediante la firma de la función EventCallback .

Después de usar OpenTrace para crear la sesión de procesamiento de seguimiento, llame a la función ProcessTrace para empezar a recibir los eventos.

Cuando ProcessTrace comienza a procesar eventos desde un seguimiento, puede invocar la devolución de llamada con uno o varios eventos sintéticos que contienen datos sobre el seguimiento (metadatos) en lugar de datos de eventos registrados. Estos eventos sintéticos tienen EventHeader.ProviderId establecido EventTraceGuid en y EventHeader.EventDescriptor.Opcode establecido en función del contenido del evento sintético. Por ejemplo, el primer evento de cada archivo de seguimiento será un evento sintético con Opcode 0 que contiene TRACE_LOGFILE_HEADER información.

Todos los demás eventos que reciba contienen datos de eventos específicos del proveedor. Use los miembros EventHeader.ProviderId y EventHeader.EventDescriptor de EVENT_RECORD para determinar el tipo de evento que recibió.

Si el evento procede de un proveedor conocido y conoce el diseño de los datos, puede usar su propio sistema para descodificar los eventos.
Si el campo EventHeader.Flags incluye la EVENT_HEADER_FLAG_TRACE_MESSAGE marca, el evento es un mensaje de WPP. Si la información de descodificación adecuada (archivo TMF o PDB) está disponible, el evento se puede descodificar mediante TdhGetProperty o TdhGetWppProperty.
De lo contrario, el evento puede ser un evento basado en MOF, basado en manifiesto o TraceLogging. Si la información de descodificación adecuada está disponible, el evento se puede descodificar mediante TdhGetEventInformation.
- Si el evento usa la descodificación basada en MOF, TdhGetEventInformation buscará información de descodificación de eventos en el almacén de datos WMI del sistema.
- Si el evento usa la descodificación basada en manifiestos, TdhGetEventInformation buscará información de descodificación de eventos en los manifiestos registrados del sistema o en manifiestos o binarios cargados en el contexto de descodificación por proceso por TdhLoadManifest o TdhLoadManifestFromBinary.
- Si el evento usa la descodificación basada en TraceLogging, TdhGetEventInformation usará información de descodificación desde dentro del evento.

En la mayoría de los casos, los eventos se entregarán a la devolución de llamada en el orden en que se produjeron (orden de marca de tiempo). Sin embargo, en determinadas circunstancias, es posible que los eventos no se entreguen en su orden original.

Si el seguimiento usa la hora del sistema para la marca de tiempo de la sesión (es decir, la sesión de seguimiento se inició con establecida en properties.Wnode.ClientContext 2) y el reloj del sistema se ajusta hacia atrás mientras la sesión recopila eventos, es posible que algunos de los eventos se entreguen desordenados. Para evitar esto, establezca ClientContext en 0 para obtener la marca de tiempo predeterminada (hora QPC).
Si el seguimiento se recopila mediante marcas de tiempo de un reloj impreciso, los eventos con la misma marca de tiempo de las CPU diferentes se pueden entregar fuera de orden. Esto ocurre con más frecuencia cuando el seguimiento usa la hora del sistema para la marca de tiempo de la sesión porque el tiempo del sistema se marca. Este problema se puede evitar iniciando la sesión con EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING en las marcas LogFileMode , aunque esto puede tener un impacto negativo sustancial en el rendimiento del seguimiento. A partir de Windows 10: El tipo de reloj de hora del sistema usa GetSystemTimePreciseAsFileTime para reducir la probabilidad de este problema.
Si el seguimiento está dañado, se generó mediante API de bajo nivel que no mantienen las reglas de marca de tiempo esperadas dentro del archivo, o usa opciones de invalidación de marca de tiempo al escribir eventos, es posible que algunos de los eventos se entreguen fuera de orden.

Técnicas: Los eventos se almacenan en búferes. Cada búfer se asigna a una secuencia de búfer, normalmente una secuencia para cada CPU. La implementación de ProcessTrace supone que todos los eventos de un búfer se ordenan por marca de tiempo y que cada búfer contiene eventos durante un único intervalo de tiempo que no se superpone al intervalo de ningún otro búfer de la secuencia del búfer. Cuando no se cumplen estas suposiciones, ProcessTracepuede entregar eventos desordenados.

Cuando una sesión de recopilación de seguimiento en tiempo real no tiene sesiones de procesamiento de seguimiento asociadas, el sistema almacenará en búfer los eventos recopilados hasta que el búfer esté lleno. Cuando una sesión de procesamiento de seguimiento se conecta a una sesión de recopilación de seguimiento en tiempo real, la sesión de procesamiento de seguimiento recibirá los eventos sintéticos de la sesión, los eventos almacenados en búfer y, a continuación, comenzará a recibir los eventos en tiempo real recién generados. Si una segunda sesión de procesamiento en tiempo real se conecta a la misma sesión de recopilación de seguimiento, recibirá los eventos sintéticos y los eventos en tiempo real recién generados (la segunda sesión de procesamiento de seguimiento no recibirá eventos anteriores).

Importante

Al procesar eventos desde una sesión en tiempo real, si la devolución de llamada de procesamiento tarda demasiado tiempo en procesar cada evento y los eventos llegan demasiado rápido, se encontrará detrás. El sistema almacenará en búfer los eventos para evitar la pérdida de datos, pero esto aumenta el uso de recursos del sistema (por ejemplo, el uso de memoria y disco). Evite este problema mediante el uso de filtros de sesión (por ejemplo, filtros de nivel y palabra clave para cada proveedor) para reducir la tasa de eventos entrantes, realizando un filtrado anticipado en la devolución de llamada para omitir eventos que no necesitan procesamiento completo y optimizar la devolución de llamada para devolver lo más rápido posible para evitar el bloqueo del subproceso de procesamiento.

Para obtener más información sobre cómo interpretar los datos del evento, consulte Consumo de eventos y recuperación de datos de eventos mediante TDH.

Requisitos


Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	evntrace.h