estructura EVENT_FILTER_DESCRIPTOR (evntprov.h)
La estructura EVENT_FILTER_DESCRIPTOR define los datos de filtro que una sesión pasa a la función de devolución de llamada enable del proveedor.
Sintaxis
typedef struct _EVENT_FILTER_DESCRIPTOR {
ULONGLONG Ptr;
ULONG Size;
ULONG Type;
} EVENT_FILTER_DESCRIPTOR, *PEVENT_FILTER_DESCRIPTOR;
Miembros
Ptr
Puntero a los datos de filtro para el tipo de filtro especificado en el miembro Type .
Si el miembro Type se establece en EVENT_FILTER_TYPE_PID, el miembro Ptr apunta a una matriz de identificadores de proceso (PID).
Si el miembro Type se establece en EVENT_FILTER_TYPE_EVENT_ID, el miembro Ptr apunta a una estructura de EVENT_FILTER_EVENT_ID que contiene una matriz de identificadores de evento y un valor booleano que determina si el seguimiento está habilitado o deshabilitado para los identificadores de evento especificados.
Si el miembro Type se establece en EVENT_FILTER_TYPE_STACKWALK, el miembro Ptr apunta a una estructura de EVENT_FILTER_EVENT_ID que contiene una matriz de identificadores de evento y un valor booleano que determina si el seguimiento de la pila está habilitado o deshabilitado para los identificadores de evento especificados.
Si el miembro Type está establecido en EVENT_FILTER_TYPE_SCHEMATIZED, consulte la estructura EVENT_FILTER_HEADER para obtener más información sobre cómo construir el filtro.
Size
Tamaño de los datos, en bytes.
El límite máximo de tamaño de datos varía en función del miembro Type especificado (el tipo del filtro). El tamaño máximo de los datos, en bytes, para muchos de los tipos de filtro se limita a MAX_EVENT_FILTER_DATA_SIZE, definido en el archivo de encabezado evntprov.h a 1024.
Type
Valor definido por el proveedor que identifica el filtro. Para los filtros definidos en un manifiesto de instrumentación, establezca este miembro en EVENT_FILTER_TYPE_SCHEMATIZED.
Los valores posibles para este miembro se definen en el archivo de encabezado evntprov.h .
EVENT_FILTER_TYPE_NONE (0x00000000)
No hay filtros.
EVENT_FILTER_TYPE_SCHEMATIZED (0x80000000)
Filtro esquematizado.
Esta es la configuración de filtrado tradicional también denominada filtrado del lado proveedor. El controlador define un conjunto personalizado de filtros como un objeto binario que se pasa al proveedor en la llamada EnableTrace, EnableTraceEx o EnableTraceEx2 . Es necesario que el controlador y el proveedor definan e interpreten estos filtros y el controlador solo debe registrar los eventos aplicables. Esto requiere un acoplamiento cercano del controlador y el proveedor, ya que no se define el tipo y el formato del objeto binario de lo que se puede filtrar. La función TdhEnumerateProviderFilters se puede usar para recuperar los filtros definidos en un manifiesto.
Para obtener más información sobre los filtros esquematizados, vea Definir filtros.
EVENT_FILTER_TYPE_SYSTEM_FLAGS (0x80000001)
Reservado para uso interno.
EVENT_FILTER_TYPE_TRACEHANDLE (0x80000002)
Se usa para capturar una lista desplegable de una sesión de seguimiento determinada. El parámetro ControlCode pasado a la función EnableTraceEx debe establecerse en EVENT_CONTROL_CODE_CAPTURE_STATE y el parámetro ProviderId debe ser SystemTraceControlGuid. La estructura EVENT_FILTER_DESCRIPTOR debe apuntar a un único TRACEHANDLE que represente una sesión ETW actual. Se realizará una lista desplegable para esa sesión determinada.
EVENT_FILTER_TYPE_PID (0x80000004)
El id. de proceso. Se trata de uno de los filtros de ámbito.
El filtrado de eventos ETW en función de los identificadores de proceso dará como resultado una secuencia de eventos (archivo o tiempo real) que contenga los eventos de los proveedores solo en los procesos especificados. Solo habilitará el proveedor en los procesos cuyos PID se proporcionan. La lista de PIN es los PID de los procesos que se ejecutan en el momento en que se llama a EnableTraceEx2 y habilitará el proveedor en todos los procesos (para los que se proporcionan LOS PID) en ese momento concreto. La lista de PID no se almacenará en la sesión. Por lo tanto, cuando se finaliza un proceso y, a continuación, vuelve a aparecer, el proveedor en él no se habilitará automáticamente en la sesión de seguimiento. El blob de filtro basado en PIDs solo es válido para una sesión de registrador de modo kernel porque la sesión del registrador privado se ejecuta dentro de un proceso en modo de usuario.
El número máximo de identificadores de proceso que se pueden filtrar está limitado por MAX_EVENT_FILTER_PID_COUNT definido en el archivo de encabezado evntprov.h a 8.
En caso de que se proporcione un filtro de identificador de proceso, el proveedor solo se habilitará en los procesos en modo de usuario. En caso de que un controlador en modo kernel registre el mismo proveedor, no se habilitará.
Esto se usa con EVENT_TRACE_PROPERTIES_V2 para registradores privados en todo el sistema.
EVENT_FILTER_TYPE_EXECUTABLE_NAME (0x80000008)
Nombre del archivo ejecutable. Se trata de uno de los filtros de ámbito.
Esto se usa con EVENT_TRACE_PROPERTIES_V2 para registradores privados en todo el sistema.
EVENT_FILTER_TYPE_PACKAGE_ID (0x80000010)
Identificador del paquete Se trata de uno de los filtros de ámbito
Esto se puede usar para filtrar proveedores a eventos emitidos desde un paquete de aplicación de la Tienda Windows determinado.
EVENT_FILTER_TYPE_PACKAGE_APP_ID (0x80000020)
Id. de aplicación relativa del paquete (PRAID). Se trata de uno de los filtros de ámbito
Esto se puede usar para filtrar proveedores a eventos emitidos desde un paquete de aplicación de la Tienda Windows determinado.
EVENT_FILTER_TYPE_PAYLOAD (0x80000100)
Carga del evento (el contenido del evento).
El tamaño máximo de datos, en bytes, para un filtro de carga de eventos se limita a MAX_EVENT_FILTER_PAYLOAD_SIZE definido en el archivo de encabezado evntprov.h a 4096.
EVENT_FILTER_TYPE_EVENT_ID (0x80000200)
El identificador de evento.
Esta característica permite habilitar o deshabilitar el filtrado para una lista de eventos. El filtro proporcionado incluye una estructura de EVENT_FILTER_EVENT_ID que contiene una matriz de identificadores de eventos y un valor booleano que indica si se va a habilitar o deshabilitar el filtrado de los eventos especificados. Cada llamada de escritura de eventos pasará rápidamente por esta matriz para averiguar si habilita o deshabilita el registro del evento.
Cuando se aplica a un proveedor de TraceLogging, este filtro se omitirá porque los eventos TraceLogging no tienen identificadores de eventos estáticos.
El número máximo de identificadores de evento permitidos en la estructura de EVENT_FILTER_EVENT_ID está limitado por MAX_EVENT_FILTER_EVENT_ID_COUNT definido en el archivo de encabezado evntprov.h a 64.
EVENT_FILTER_TYPE_EVENT_NAME (0x80000400)
Nombre del evento TraceLogging.
Esta característica permite habilitar o deshabilitar los eventos traceLogging en función de sus nombres. El filtro proporcionado incluye una estructura de EVENT_FILTER_EVENT_NAME que contiene una matriz de nombres de eventos, máscaras de bits de palabra clave y nivel para filtrar, y un valor booleano que indica si se deben habilitar o deshabilitar los eventos descritos. Cuando se aplica a un proveedor que no es TraceLogging, este filtro se omite porque esos eventos no tienen nombres especificados en su carga.
Nota: Disponible en Windows 10, versión 1709 y posteriores.
EVENT_FILTER_TYPE_STACKWALK (0x80001000)
Un paseo por la pila.
Cuando el recorrido por la pila está habilitado para un proveedor, la pila se captura para todos los eventos generados por el proveedor. La mayoría de las veces, el usuario solo está interesado en la pila de un número determinado de eventos.
Esta característica permite habilitar o deshabilitar la pila caminando en una lista de eventos. El filtro proporcionado incluye una estructura de EVENT_FILTER_EVENT_ID que contiene una matriz de identificadores de eventos y un valor booleano que indica si se debe habilitar o deshabilitar la captura de la pila para los eventos especificados. Cada llamada de escritura de eventos pasará por esta matriz rápidamente para averiguar si la pila se debe capturar o no.
Cuando se aplica a un proveedor de TraceLogging, este filtro se omitirá porque los eventos TraceLogging no tienen identificadores de eventos estáticos.
Si decide usar este filtro, debe especificar EVENT_ENABLE_PROPERTY_STACK_TRACE en la estructura de ENABLE_TRACE_PARAMETERS al habilitar el proveedor para que se recopilen las pilas de un proveedor.
El número máximo de identificadores de evento permitidos en la estructura de EVENT_FILTER_EVENT_ID está limitado por MAX_EVENT_FILTER_EVENT_ID_COUNT definido en el archivo de encabezado evntprov.h a 64.
Nota: Disponible en Windows 10, versión 1709 y posteriores.
EVENT_FILTER_TYPE_STACKWALK_NAME (0x80002000)
Un nombre de evento TraceLogging.
Esta característica permite filtrar la colección de pilas para los eventos TraceLogging en función de los nombres de evento. El filtro proporcionado incluye una estructura de EVENT_FILTER_EVENT_NAME que contiene una matriz de nombres de eventos, máscaras de bits de palabra clave y nivel para filtrar, y un valor booleano que indica si se van a recopilar pilas o no para los eventos descritos.
Cuando se aplica a un proveedor que no es TraceLogging, este filtro se omite porque esos eventos no tienen nombres especificados en su carga.
Si decide usar este filtro, debe especificar EVENT_ENABLE_PROPERTY_STACK_TRACE en la estructura de ENABLE_TRACE_PARAMETERS al habilitar el proveedor para que se recopilen las pilas de un proveedor.
Nota: Disponible en Windows 10, versión 1709 y posteriores.
EVENT_FILTER_TYPE_STACKWALK_LEVEL_KW (0x80004000)
Nivel de evento y palabra clave.
Esta característica permite filtrar la colección de pilas para eventos en función de su nivel y palabra clave. El filtro proporcionado incluye una estructura de EVENT_FILTER_LEVEL_KW que contiene máscaras de bits de palabra clave y nivel para filtrar, así como un valor booleano que indica si se van a recopilar pilas o no para los eventos descritos.
Si decide usar este filtro, debe especificar EVENT_ENABLE_PROPERTY_STACK_TRACE en la estructura de ENABLE_TRACE_PARAMETERS al habilitar el proveedor para que se recopilen las pilas de un proveedor.
Nota: Disponible en Windows 10, versión 1709 y posteriores.
Comentarios
El proveedor determina el diseño de los datos y su propósito.
En Windows 8.1, windows Server 2012 R2 y versiones posteriores, los filtros de recorrido de eventos, ámbito y pila se pueden usar mediante la función EnableTraceEx2 y las estructuras de ENABLE_TRACE_PARAMETERS y EVENT_FILTER_DESCRIPTOR para filtrar por condiciones específicas en una sesión del registrador. Para obtener más información sobre los filtros de carga de eventos, consulte las funciones EnableTraceEx2, TdhCreatePayloadFilter y TdhAggregatePayloadFilters y las estructuras ENABLE_TRACE_PARAMETERS y PAYLOAD_FILTER_PREDICATE .
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 |
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de