структура EVENT_FILTER_DESCRIPTOR (evntprov.h)

Статья
08/23/2023

Структура EVENT_FILTER_DESCRIPTOR определяет данные фильтра, которые сеанс передает в функцию обратного вызова enable поставщика.

Синтаксис

typedef struct _EVENT_FILTER_DESCRIPTOR {
  ULONGLONG Ptr;
  ULONG     Size;
  ULONG     Type;
} EVENT_FILTER_DESCRIPTOR, *PEVENT_FILTER_DESCRIPTOR;

Члены

Ptr

Указатель на данные фильтра для типа фильтра, указанного в элементе Type .

Если для элемента Type задано значение EVENT_FILTER_TYPE_PID, то элемент Ptr указывает на массив идентификаторов процессов (PID).

Если для элемента Type задано значение EVENT_FILTER_TYPE_EVENT_ID, то элемент Ptr указывает на EVENT_FILTER_EVENT_ID структуру, содержащую массив идентификаторов событий и логическое значение, определяющее, включена или отключена трассировка для указанных идентификаторов событий.

Если для элемента Type задано значение EVENT_FILTER_TYPE_STACKWALK, то элемент Ptr указывает на EVENT_FILTER_EVENT_ID структуру, содержащую массив идентификаторов событий и логическое значение, определяющее, включена или отключена трассировка стека для указанных идентификаторов событий.

Если для элемента Type задано значение EVENT_FILTER_TYPE_SCHEMATIZED, дополнительные сведения о создании фильтра см . в EVENT_FILTER_HEADER структуре.

Size

Размер данных в байтах.

Максимальный размер данных зависит от указанного элемента Type (типа фильтра). Максимальный размер данных (в байтах) для многих типов фильтров ограничен MAX_EVENT_FILTER_DATA_SIZE, определенным в файле заголовка evntprov.h до 1024.

Type

Определенное поставщиком значение, идентифицирующее фильтр. Для фильтров, определенных в манифесте инструментирования, задайте для этого элемента значение EVENT_FILTER_TYPE_SCHEMATIZED.

Возможные значения для этого элемента определяются в файле заголовка evntprov.h .

EVENT_FILTER_TYPE_NONE (0x00000000)

Фильтры отсутствуют.
EVENT_FILTER_TYPE_SCHEMATIZED (0x80000000)

Схематизированный фильтр.

Это традиционная настройка фильтрации, также называемая фильтрацией на стороне поставщика. Контроллер определяет настраиваемый набор фильтров в виде двоичного объекта, который передается поставщику в вызове EnableTrace, EnableTraceEx или EnableTraceEx2 . Контроллер и поставщик должны определять и интерпретировать эти фильтры, и контроллер должен регистрировать только применимые события. Для этого требуется тесная связь контроллера и поставщика, так как тип и формат двоичного объекта объекта , который может быть отфильтрован, не определен. Для получения фильтров, определенных в манифесте, можно использовать функцию TdhEnumerateProviderFilters .

Дополнительные сведения о схематизированных фильтрах см. в разделе Определение фильтров.
EVENT_FILTER_TYPE_SYSTEM_FLAGS (0x80000001)

Зарезервировано для внутреннего использования.
EVENT_FILTER_TYPE_TRACEHANDLE (0x80000002)

Используется для записи состояния определенного сеанса трассировки. Параметр ControlCode , передаваемый в функцию EnableTraceEx , должен иметь значение EVENT_CONTROL_CODE_CAPTURE_STATE а параметр ProviderId должен иметь значение SystemTraceControlGuid. Структура EVENT_FILTER_DESCRIPTOR должна указывать на один объект TRACEHANDLE , представляющий текущий сеанс трассировки событий Windows. Для конкретного сеанса будет выполнено прогона.
EVENT_FILTER_TYPE_PID (0x80000004)

Идентификатор процесса. Это один из область фильтров.

Фильтрация событий трассировки событий Windows по идентификаторам процессов приведет к созданию потока событий (файла или в режиме реального времени), содержащего события от поставщиков только в указанных процессах. Он будет включать поставщика только в процессах, для которых предоставляются идентификаторы PID. Список ИДЕНТИФИКАТОРов — это идентификаторы PID процессов, выполняющихся в момент вызова EnableTraceEx2 , которые будут включать поставщика во всех процессах (для которых предоставляются идентификаторы PID) в указанное время. Список ИДЕНТИФИКАТОРов не будет храниться в сеансе. Таким образом, когда процесс завершается, а затем снова появляется, поставщик в нем не будет автоматически включен в сеанс трассировки. Blob-объект фильтра на основе PID действителен только для сеанса средства ведения журнала в режиме ядра, так как частный сеанс средства ведения журнала выполняется внутри процесса пользовательского режима.

Максимальное число идентификаторов процессов, которые можно фильтровать, ограничено MAX_EVENT_FILTER_PID_COUNT , определенным в файле заголовка evntprov.h , до 8.

Если указан фильтр идентификатора процесса, поставщик будет включен только в процессах пользовательского режима. В случае, если тот же поставщик зарегистрирован драйвером режима ядра, он не будет включен.

Используется с EVENT_TRACE_PROPERTIES_V2 для частных средств ведения журнала на уровне системы.
EVENT_FILTER_TYPE_EXECUTABLE_NAME (0x80000008)

Имя исполняемого файла. Это один из область фильтров.

Используется с EVENT_TRACE_PROPERTIES_V2 для частных средств ведения журнала на уровне системы.
EVENT_FILTER_TYPE_PACKAGE_ID (0x80000010)

ИД пакета; Это один из область фильтров

Это можно использовать для фильтрации поставщиков по событиям, созданным из определенного пакета приложения Магазина Windows.
EVENT_FILTER_TYPE_PACKAGE_APP_ID (0x80000020)

Идентификатор приложения относительно пакета (PRAID). Это один из область фильтров

Это можно использовать для фильтрации поставщиков по событиям, созданным из определенного пакета приложения Магазина Windows.
EVENT_FILTER_TYPE_PAYLOAD (0x80000100)

Полезные данные события (содержимое события).

Максимальный размер данных (в байтах) для фильтра полезных данных событий ограничен MAX_EVENT_FILTER_PAYLOAD_SIZE определен в файле заголовка evntprov.h до 4096.
EVENT_FILTER_TYPE_EVENT_ID (0x80000200)

Идентификатор события.

Эта функция позволяет включить или отключить фильтрацию для списка событий. Предоставленный фильтр включает структуру EVENT_FILTER_EVENT_ID , содержащую массив идентификаторов событий и логическое значение, указывающее, следует ли включать или отключать фильтрацию для указанных событий. Каждый вызов записи события будет быстро проходить через этот массив, чтобы узнать, включить или отключить ведение журнала события.

При применении к поставщику TraceLogging этот фильтр будет игнорироваться, так как события TraceLogging не имеют статических идентификаторов событий.

Максимальное число идентификаторов событий, разрешенное в структуре EVENT_FILTER_EVENT_ID , ограничено MAX_EVENT_FILTER_EVENT_ID_COUNT , определенным в файле заголовка evntprov.h , до 64.
EVENT_FILTER_TYPE_EVENT_NAME (0x80000400)

Имя события TraceLogging.

Эта функция позволяет включить или отключить события TraceLogging на основе их имен. Предоставленный фильтр включает в себя структуру EVENT_FILTER_EVENT_NAME, содержащую массив имен событий, ключевое слово битовые маски и уровни для фильтрации, а также логическое значение, указывающее, следует ли включать или отключать описанные события. При применении к поставщику, отличному от TraceLogging, этот фильтр игнорируется, так как эти события не имеют имен, указанных в полезных данных.

Примечание: Доступно в Windows 10 версии 1709 и более поздних.
EVENT_FILTER_TYPE_STACKWALK (0x80001000)

Прогулка по стеку.

Если для поставщика включена функция обхода стека, стек фиксируется для всех событий, созданных поставщиком. В большинстве случаев пользователя интересует только стек из определенного количества событий.

Эта функция позволяет включать или отключать стек для просмотра списка событий. Предоставленный фильтр содержит структуру EVENT_FILTER_EVENT_ID , содержащую массив идентификаторов событий и логическое значение, указывающее, следует ли включать или отключать запись стека для указанных событий. Каждый вызов записи события будет быстро проходить через этот массив, чтобы узнать, следует ли записывать стек.

При применении к поставщику TraceLogging этот фильтр будет игнорироваться, так как события TraceLogging не имеют статических идентификаторов событий.

Если вы решите использовать этот фильтр, необходимо указать EVENT_ENABLE_PROPERTY_STACK_TRACE в структуре ENABLE_TRACE_PARAMETERS при включении поставщика для сбора любых стеков от поставщика.

Максимальное число идентификаторов событий, разрешенное в структуре EVENT_FILTER_EVENT_ID , ограничено MAX_EVENT_FILTER_EVENT_ID_COUNT , определенным в файле заголовка evntprov.h , до 64.

Примечание: Доступно в Windows 10 версии 1709 и более поздних.
EVENT_FILTER_TYPE_STACKWALK_NAME (0x80002000)

Имя события TraceLogging.

Эта функция позволяет фильтровать коллекцию стека для событий TraceLogging на основе имен событий. Предоставленный фильтр включает EVENT_FILTER_EVENT_NAME структуру, которая содержит массив имен событий, ключевое слово битовые маски и уровень для фильтрации, а также логическое значение, указывающее, собирать ли стеки для описанных событий.

При применении к поставщику, отличному от TraceLogging, этот фильтр игнорируется, так как эти события не имеют имен, указанных в полезных данных.

Если вы решили использовать этот фильтр, необходимо указать EVENT_ENABLE_PROPERTY_STACK_TRACE в структуре ENABLE_TRACE_PARAMETERS при включении поставщика для сбора всех стеков от поставщика.

Примечание: Доступно в Windows 10 версии 1709 и более поздних.
EVENT_FILTER_TYPE_STACKWALK_LEVEL_KW (0x80004000)

Уровень событий и ключевое слово.

Эта функция позволяет фильтровать коллекцию стека по событиям на основе их уровня и ключевое слово. Предоставленный фильтр содержит EVENT_FILTER_LEVEL_KW структуру, которая содержит ключевое слово битовые маски и уровень для фильтрации, а также логическое значение, указывающее, следует ли собирать стеки для описанных событий.

Если вы решили использовать этот фильтр, необходимо указать EVENT_ENABLE_PROPERTY_STACK_TRACE в структуре ENABLE_TRACE_PARAMETERS при включении поставщика для сбора всех стеков от поставщика.

Примечание: Доступно в Windows 10 версии 1709 и более поздних.

В Windows 8.1,Windows Server 2012 R2 и более поздних версий полезные данные событий, область и стеки могут использоваться функцией EnableTraceEx2, а также структурами ENABLE_TRACE_PARAMETERS и EVENT_FILTER_DESCRIPTOR для фильтрации по определенным условиям в сеансе средства ведения журнала. Дополнительные сведения о фильтрах полезных данных событий см. в статьях Функции EnableTraceEx2, TdhCreatePayloadFilter и TdhAggregatePayloadFilters , а также структуры ENABLE_TRACE_PARAMETERS и PAYLOAD_FILTER_PREDICATE .

Требования


Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Верхняя часть	evntprov.h