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

Статья
03/11/2023

Структура EVENT_DESCRIPTOR содержит сведения (метаданные) о событии трассировки событий Windows.

Синтаксис

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

Члены

Id

16-разрядное число, используемое для идентификации событий на основе манифеста.

Для трассировки событий windows на основе манифеста сочетание Provider.DecodeGuid + Event.Id + Event.Version должно однозначно идентифицировать событие, т. е. все события с одинаковым DecodeGuid, Id и Version должны иметь одинаковый набор полей без изменений в именах полей, типах полей или упорядочении полей.

Для трассировки событий windows без манифеста (т. е. TraceLogging) поле Id обычно не имеет смысла и обычно имеет значение 0. События TraceLogging обычно идентифицируются по имени события, а не по идентификатору события.

Version

8-разрядное число, используемое для указания версии события на основе манифеста.

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

Channel

8-разрядное число, используемое для включения специальной обработки событий.

События на основе манифеста обычно используют канал 0.
События на основе TraceLogging обычно используют канал 11.
События на основе манифеста с признаками поставщика обычно используют канал 12.
Другие значения канала могут использоваться с событиями журнала событий.

Значения каналов ниже 16 зарезервированы для использования корпорацией Майкрософт, чтобы обеспечить специальную обработку в среде выполнения трассировки событий Windows. Значения канала 16 и выше будут игнорироваться средой выполнения ETW (обрабатывается так же, как канал 0) и могут быть предоставлены определяемой пользователем семантике.

Level

8-битовое число, используемое для описания серьезности или важности события.

Важно!

Уровень событий является основным средством фильтрации событий. Всегда присваивайте каждому событию значимый (ненулевой) уровень.

Значения уровней от 0 до 5 определяются корпорацией Майкрософт (см. evntrace.h и winmeta.h). Зарезервированы значения уровней от 6 до 15. Значения уровней от 16 до 255 могут быть определены поставщиком событий.

Значение	Семантика
LOG_ALWAYS (0)	Событие обходит фильтрацию событий на основе уровня. События не должны использовать этот уровень.
КРИТИЧЕСКОЕ (1)	Критическая ошибка
ОШИБКА (2)	Ошибка
ПРЕДУПРЕЖДЕНИЕ (3)	Предупреждение
INFO (4)	Informational
VERBOSE (5)	Подробный

Сеансы сбора событий могут задать фильтр уровня, то есть сеанс будет принимать события только там, где eventDescriptor.Level <= session.LevelFilter. Обратите внимание, что события с уровнем 0 обходят фильтрацию на основе уровня.

Opcode

8-разрядное число, используемое для пометки событий с помощью специальной семантики. Это значение может использоваться декодировщиками трассировки для упорядочения и корреляции событий. Глобально распознаваемые значения opcode определяются в winmeta.h. Большинство событий используют INFO (0). Значения opcode от 10 до 239 можно задать определяемую пользователем семантику.

Коды операций START (1) и STOP (2) используются для обозначения начала и окончания действий ETW следующим образом:

Создайте уникальный идентификатор действия в трассировки, как правило, с помощью EventActivityIdControl.
Напишите событие start с кодом операции = START, идентификатором действия = созданным идентификатором действия и идентификатором связанного действия = идентификатором родительского действия (если таковой имеется).
Записывайте любое количество событий сведений о действиях с кодом операции — INFO, идентификатором действия — созданным идентификатором действия.
Запись события остановки с помощью opcode = STOP, идентификатор действия = созданный идентификатор действия.

Затем средства декодирования трассировки могут упорядочивать эти события в группы на основе идентификаторов их действий.

Task

16-разрядное число, используемое для примечания к событию или связанной группе событий.

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

Keyword

64-разрядная битовая маска, используемая для указания членства события в наборе категорий событий.

Важно!

Ключевое слово событий является основным средством фильтрации событий. Всегда присваивайте каждому событию осмысленное (ненулевое) ключевое слово.

Первые 16 бит ключевое слово (0xFFFF000000000000 битовой маски) определяются корпорацией Майкрософт. Низкие 48 бит ключевое слово (0x0000FFFFFFFFFFFF битовой маски) определяются поставщиком событий. Например, поставщик событий может определить бит 0 (битовая маска 0x1) как категорию ввода-вывода, бит 1 (битовая маска 0x2) — категорию пользовательского интерфейса, а бит 2 (битовая маска 0x4) — категорию измерения производительности. В этом сценарии для события может быть задано ключевое слово значение 0x5, что указывает на то, что оно относится как к категориям ввода-вывода, так и к категории "измерение производительности".

Сеансы сбора событий могут задавать фильтры MatchAnyKeyword и MatchAllKeyword. Это означает, что сеанс будет принимать только события, в которых имеет значение true следующее выражение:

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

Обратите внимание, что события с ключевое слово 0 обычно обходят фильтрацию на основе ключевое слово.

Совет

Начиная с Windows 10 версии 1507 и более поздних, сеанс сбора событий может исключать события, для которых ключевое слово задано значение 0. Для этого включите EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 флаг в EnableProperty поле структуры ENABLE_TRACE_PARAMETERS , которая передается в EnableTraceEx2 при настройке поставщика.

Эта структура используется при вызове EventWrite для записи события. Его также можно использовать при вызове EventEnabled , чтобы определить, следует ли создавать событие (т. е. определить, заинтересованы ли прослушиватели событий в событии).

Примечание

Большинство поставщиков событий не будут использовать EVENT_DESCRIPTOR напрямую. Вместо этого большинство поставщиков событий реализуются с помощью платформы трассировки событий Windows, которая заключает вызовы EventRegister, EventWriteEx и EventUnregister. Например, можно написать манифест события , а затем использовать компилятор сообщений для создания кода C/C++ для событий, или использовать TraceLogging , чтобы избежать необходимости в манифесте. Дополнительные сведения о том, как члены этой структуры связаны с манифестом инструментирования, см. в атрибутах сложного типа EventDefinitionType .

Эта структура включена в структуру EVENT_HEADER , которая возвращается вместе с записью события при использовании событий с помощью ProcessTrace с обратным вызовом EventRecordCallback .

Примечание

При обработке событий на основе MOF удостоверение события содержится в поле Opcode , а не в поле Id .

Требования

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