estructura EVENT_DESCRIPTOR (evntprov.h)

Artículo
08/23/2023

La estructura EVENT_DESCRIPTOR contiene información (metadatos) sobre un evento ETW.

Sintaxis

typedef struct _EVENT_DESCRIPTOR {
  USHORT    Id;
  UCHAR     Version;
  UCHAR     Channel;
  UCHAR     Level;
  UCHAR     Opcode;
  USHORT    Task;
  ULONGLONG Keyword;
} EVENT_DESCRIPTOR, *PEVENT_DESCRIPTOR;

Miembros

Id

Número de 16 bits que se usa para identificar eventos basados en manifiestos.

En el caso de ETW basado en manifiestos, la combinación Provider.DecodeGuid + Event.Id + Event.Version debe identificar de forma única un evento, es decir, todos los eventos con el mismo DecodeGuid, Id y Version deben tener el mismo conjunto de campos sin cambios en los nombres de campo, los tipos de campo o la ordenación de campos.

En el caso de ETW sin manifiesto (es decir, TraceLogging), el campo Id no suele ser significativo y normalmente se establecerá en 0. Los eventos traceLogging se identifican generalmente por su nombre de evento, no por el identificador de evento.

Version

Número de 8 bits usado para especificar la versión de un evento basado en manifiesto.

La versión indica una revisión de la definición de un evento con un identificador determinado. Todos los eventos con un identificador determinado deben tener una semántica similar, pero se puede usar un cambio en la versión para indicar una modificación secundaria de los detalles del evento, por ejemplo, un cambio en el tipo de un campo o la adición de un nuevo campo.

Channel

Número de 8 bits que se usa para habilitar el procesamiento de eventos especiales.

Los eventos basados en manifiesto suelen usar el canal 0.
Los eventos basados en el registro de seguimiento usan normalmente el canal 11.
Los eventos basados en manifiestos con rasgos de proveedor usan normalmente el canal 12.
Se pueden usar otros valores de canal con eventos del registro de eventos.

Los valores de canal inferiores a 16 están reservados para su uso por Parte de Microsoft para habilitar el tratamiento especial por parte del tiempo de ejecución de ETW. El tiempo de ejecución de ETW omitirá los valores de canal 16 y posteriores (tratados iguales que el canal 0) y se puede dar semántica definida por el usuario.

Level

Número de 8 bits que se usa para describir la gravedad o importancia de un evento.

Importante

El nivel de evento es un medio principal para filtrar eventos. Asigne siempre un nivel significativo (distinto de cero) a cada evento.

Microsoft define los valores de nivel 0 a 5 (consulte evntrace.h y winmeta.h). Los valores de nivel 6 a 15 están reservados. El proveedor de eventos puede definir los valores de nivel de 16 a 255.

Valor	Semántica
LOG_ALWAYS (0)	El evento omite el filtrado de eventos basado en el nivel. Los eventos no deben usar este nivel.
CRITICAL (1)	Error grave
ERROR (2)	Error
ADVERTENCIA (3)	Advertencia
INFO (4)	Informativo
VERBOSE (5)	Verbose

Las sesiones de recopilación de eventos pueden establecer un filtro de nivel, lo que significa que la sesión solo aceptará eventos en los que eventDescriptor.Level <= session.LevelFilter. Tenga en cuenta que los eventos con un nivel de 0 omitirán el filtrado basado en el nivel.

Opcode

Número de 8 bits usado para marcar eventos con semántica especial. Los descodificadores de seguimiento pueden usar este valor para organizar y correlacionar eventos. Los valores de código de operación reconocidos globalmente se definen en winmeta.h. La mayoría de los eventos usan INFO (0). Los valores de opcode de 10 a 239 se pueden proporcionar semántica definida por el usuario.

Los códigos de operación START (1) y STOP (2) se usan para indicar el principio y el final de las actividades ETW de la siguiente manera:

Genere un identificador de actividad que sea único dentro del seguimiento, normalmente mediante EventActivityIdControl.
Escriba un evento de inicio con opcode = START, id. de actividad = el identificador de actividad generado y el identificador de actividad relacionado = el identificador de actividad primario (si existe).
Escriba cualquier número de eventos de información de actividad con opcode = INFO, id. de actividad = el identificador de actividad generado.
Escriba un evento stop con opcode = STOP, id. de actividad = el identificador de actividad generado.

Las herramientas de descodificación de seguimiento pueden organizar estos eventos en grupos en función de sus identificadores de actividad.

Task

Número de 16 bits usado para anotar un evento o un grupo de eventos relacionado.

El código de la tarea de evento se puede usar para cualquier propósito definido por el proveedor. El código de tarea 0 es el valor predeterminado, que se usa para indicar que no se ha asignado ningún código de tarea especial al evento. El manifiesto ETW admite la asignación de cadenas localizadas a cada código de tarea. El código de tarea se puede usar para agrupar eventos en categorías o simplemente para asociar una cadena "tarea" localizada a cada evento.

Keyword

Máscara de bits de 64 bits que se usa para indicar la pertenencia de un evento en un conjunto de categorías de eventos.

Importante

La palabra clave Event es un medio principal para filtrar eventos. Asigne siempre una palabra clave significativa (distinto de cero) a cada evento.

Microsoft define los 16 bits principales de la palabra clave (máscara de bits 0xFFFF000000000000). El proveedor de eventos define los 48 bits bajos de la palabra clave (máscara de bits 0x0000FFFFFFFFFFFF). Por ejemplo, el proveedor de eventos podría definir el bit 0 (máscara de bits 0x1) para que sea la categoría "E/S", bit 1 (máscara de bits 0x2) para que sea la categoría "UI" y bit 2 (máscara de bits 0x4) para que sea la categoría "medida de rendimiento". En este escenario, un evento podría tener su palabra clave establecida en 0x5, lo que indica que el evento está en las categorías "E/S" y "medida de rendimiento".

Las sesiones de recopilación de eventos pueden establecer filtros MatchAnyKeyword y MatchAllKeyword, lo que significa que la sesión solo aceptará eventos en los que la expresión siguiente sea verdadera:

eventDescriptor.Keyword == 0 || (
    (eventDescriptor.Keyword & session.MatchAnyKeyword) != 0 &&
    (eventDescriptor.Keyword & session.MatchAllKeyword) == session.MatchAllKeyword
)

Tenga en cuenta que los eventos con una palabra clave 0 normalmente omitirán el filtrado basado en palabras clave.

Sugerencia

A partir de Windows 10 versión 1507 y posteriores, una sesión de recopilación de eventos puede excluir eventos que tengan su palabra clave establecida en 0. Para ello, incluya la EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 marca en el EnableProperty campo de la estructura de ENABLE_TRACE_PARAMETERS que se pasa a EnableTraceEx2 al configurar el proveedor.

Comentarios

Esta estructura se usa al llamar a EventWrite para escribir el evento. También puede usarlo al llamar a EventEnabled para determinar si se debe generar el evento (es decir, para determinar si algún agente de escucha de eventos está interesado en el evento).

Nota

La mayoría de los proveedores de eventos no usarán EVENT_DESCRIPTOR directamente. 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. Para obtener más información sobre cómo se relacionan los miembros de esta estructura con el manifiesto de instrumentación, vea los atributos del tipo complejo EventDefinitionType .

Esta estructura se incluye en la estructura EVENT_HEADER que se devuelve con el registro de eventos cuando se consumen eventos mediante ProcessTrace con la devolución de llamada EventRecordCallback .

Nota

Al procesar eventos basados en MOF, la identidad del evento se encuentra en el campo Opcode , no en el campo Id .

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Encabezado	evntprov.h (incluye Evntprov.h)