estructura EVENT_DESCRIPTOR (evntprov.h)

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 usado para identificar eventos basados en manifiestos.

Para 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 el orden de campos.

Para ETW sin manifiesto (es decir, TraceLogging), el campo Id no suele ser significativo y normalmente se establecerá en 0. Los eventos traceLogging suelen identificarse 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 usado para habilitar el procesamiento de eventos especiales.

  • Normalmente, los eventos basados en manifiestos usan el canal 0.
  • Los eventos basados en traceLogging normalmente usan el canal 11.
  • Los eventos basados en manifiestos con rasgos de proveedor normalmente usan 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 usado 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.

Value Semántica
LOG_ALWAYS (0) El evento omite el filtrado de eventos basado en el nivel. Los eventos no deben usar este nivel.
CRÍTICO (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 eventDescriptor.Level <= session.LevelFilterlos que . 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 código de operación 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:

  1. Genere un identificador de actividad que sea único dentro del seguimiento, normalmente mediante EventActivityIdControl.
  2. 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).
  3. Escriba cualquier número de eventos de información de actividad con opcode = INFO, id. de actividad = el identificador de actividad generado.
  4. 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 asociar una cadena "tarea" localizada a cada evento.

Keyword

Máscara de bits de 64 bits usada 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 (distinta 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 "medición 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 "medición 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 se cumple la siguiente expresión:

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 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 encapsula 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, consulte 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

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

Consulte también

EVENT_HEADER

EventDescCreate

EventDescGetChannel

EventDescGetId

EventDescGetKeyword

EventDescGetLevel

EventDescGetOpcode

EventDescGetTask

EventDescGetVersion

EventDescOrKeyword

EventDescSetChannel

EventDescSetId

EventDescSetKeyword

EventDescSetLevel

EventDescSetOpcode

EventDescSetTask

EventDescSetVersion

EventDescZero

EventEnabled

EventWrite

EventWriteTransfer

PROVIDER_EVENT_INFO

TdhEnumerateManifestProviderEvents

TdhGetManifestEventInformation