Признаки поставщика

Признаки поставщика — это метод присоединения дополнительных данных к регистрации отдельного поставщика. Их можно использовать для поставщиков traceLogging на основе манифеста или трассировки. В настоящее время это включает поддержку добавления имени поставщика и /или группы поставщиков в отдельную регистрацию поставщика. В будущем будут добавлены дополнительные типы признаков. Эти сведения хранятся в ядре в виде двоичного большого двоичного объекта заданного формата.

Признаки можно задать только один раз для регистрации. Любые дальнейшие попытки задать признаки для этой регистрации завершаются ошибкой.

Чтобы задать признаки поставщика на основе манифеста, вызовите функцию EventSetInformation с классом сведений EventProviderSetTraits. Буфер EventInformation должен содержать двоичный большой двоичный объект следующего формата:

{
   UINT16 TraitsSize   // Total size of the traits including this field
   CHAR[] ProviderName // Null terminated utf-8 provider name
   TRAIT[] Traits      // Zero or more individual traits
}

Отдельные признаки должны иметь следующий формат:

TRAIT {
      UINT16 TraitSize // Size of this individual trait including this field
      UINT8 Type       // ETW_PROVIDER_TRAIT_TYPE
      BYTE[] Data
      }

Из отдельного признака ETW_PROVIDER_TRAIT_TYPE определяется следующим образом:

typedef enum {
    EtwProviderTraitTypeGroup = 1,
    EtwProviderTraitTypeMax
} ETW_PROVIDER_TRAIT_TYPE;

Поставщики TraceLogging автоматически задают признаки поставщика при вызове функции TraceLoggingRegister. Имя поставщика TraceLogging всегда будет включено в его признаки. Группу можно задать в поставщике TraceLogging с помощью макроса traceLoggingOptionGroup в определении поставщика.

Настраиваемые признаки

Хотя большинство из 255 возможных типов признаков еще не определены, признаки 1-127 зарезервированы для определения корпорацией Майкрософт. Остальные более высокие индексированные значения типов можно использовать внешними разработчиками по мере их соответствия. Любой пользователь, желающий добавить собственные пользовательские черты к своему поставщику, должен попытаться сохранить свой общий размер признака менее 256 байт по следующим причинам:

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

Группы поставщиков

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

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

В некоторых случаях контроллер сеанса трассировки может потребоваться исключить несколько поставщиков из его включения группы. Это можно сделать, задав список запретов. Список запретов — это список идентификаторов GUID поставщика, которые не будут включены на основе параметров группы для одного сеанса ведения журнала. Списки запретов можно динамически изменять с помощью TraceSetInformation и класса сведений TraceSetDisallowList.

Хотя большинство действий включения можно выполнять для групп поставщиков аналогичным образом с отдельными поставщиками, существуют некоторые исключения. К исключениям относятся:

• Группы поставщиков не могут контролироваться сеансами частной трассировки.
• Фильтры "Имя события", "Идентификатор события" и "Полезные данные" не применимы к группам поставщиков, так как они предполагают определенную информацию отдельного поставщика.