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

Признаки поставщика — это метод присоединения дополнительных данных к регистрации отдельного поставщика. Их можно использовать для поставщиков на основе манифеста или TraceLogging. В настоящее время это включает поддержку добавления имени поставщика и (или) группы поставщиков в отдельную регистрацию поставщика. Скорее всего, в будущем будут добавлены другие типы признаков. Эти сведения хранятся в ядре в виде двоичного BLOB-объекта заданного формата.

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

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

{
   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.

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

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