Макрос TraceLoggingChannel (traceloggingprovider.h)

Статья
03/13/2024

Макрос-оболочка TraceLogging , который задает канал для события.

Большинству событий TraceLogging не требуется изменять канал события по умолчанию и не следует использовать TraceLoggingChannel.

Синтаксис

void TraceLoggingChannel(
  [in]  eventChannel
);

Параметры

[in] eventChannel

Канал, в котором должно быть зарегистрировано событие. Это целочисленное значение от 0 до 255.

Дополнительные сведения о канале событий см. в разделе EVENT_DESCRIPTOR .

Возвращаемое значение

None

Remarks

TraceLoggingChannel(eventChannel) можно использовать в качестве параметра для вызова макроса TraceLoggingWrite . Большинству событий TraceLogging не требуется изменять канал события по умолчанию и не следует использовать TraceLoggingChannel.

Параметр eventChannel должен быть константой времени компиляции от 0 до 255. Если аргумент не TraceLoggingChannel(n) указан, канал по умолчанию — 11 (WINEVENT_CHANNEL_TRACELOGGING), что указывает на то, что это обычное событие TraceLogging. Если указано несколько TraceLoggingChannel(n) аргументов, будет использоваться значение из последнего TraceLoggingChannel(n) параметра.

Каналы используются в расширенных сценариях трассировки событий Windows (ETW). К ним относится запись в определяемые системой потребители событий, такие как журнал событий Windows.

Предупреждение

Если поставщик будет работать в Windows раньше, чем Windows 10, не используйте TraceLoggingChannel. Чтобы декодеры событий распознали событие как совместимое с TraceLogging, оно должно иметь значение по умолчанию для канала (11) или должно быть отмечено как событие TraceLogging средой выполнения трассировки событий Windows во время eventWrite. Эта маркировка событий включается путем вызова EventSetInformation для настройки поставщика в качестве поставщика TraceLogging. EventSetInformation в Windows 10 или более поздних версиях включает поддержку событий TraceLogging независимо от канала, но в более ранних версиях Windows требуется обновление Windows, прежде чем они будут поддерживать маркировку событий TraceLogging. Для событий, захваченных в системах без обновленного EventSetInformation, канал 11 — единственный способ распознать событие TraceLogging, поэтому события с другими каналами могут декодироваться неправильно.

TraceLogging и журнал событий

В большинстве случаев разработчики используют трассировку событий windows на основе манифеста для событий, которые должны быть записаны в журнале событий. Журнал событий в первую очередь предназначен для сбора небольших событий, которые могут быть полезны администратору системы. Трассировка событий Windows на основе манифеста хорошо подходит для этого, так как она поддерживает тщательно курируемые события (все события для компонента описаны в одном файле манифеста) и поддерживает локализуемые строки сообщений, которые могут помочь администратору узнать, как реагировать на событие.

Хотя события TraceLogging не имеют строк сообщений и обычно не курируются централизованно, TraceLogging по-прежнему может подходить для некоторых сценариев журнала событий. Например, хотя события, которые идут в журналы Windows (приложения, безопасность, установка и система), всегда должны иметь локализованные строки сообщений и всегда должны быть полезны системным администратором, события, записанные в журналах приложений и служб, могут быть более техническими и могут записывать диагностические сведения. При записи в журналы приложений и служб может потребоваться использовать TraceLogging, чтобы упростить управление зарегистрированными событиями.

Использование событий TraceLogging с журналом событий Windows аналогично использованию обычных событий на основе манифеста с журналом событий. Вам по-прежнему нужно создать и зарегистрировать манифест для определения поставщика и каналов, но вам не нужно определять отдельные события в манифесте:

Напишите манифест трассировки событий Windows , определяющий поставщика и каналы журнала событий. Поставщик в манифесте должен использовать то же имя поставщика и guid поставщика (идентификатор поставщика), что и в макросе TRACELOGGING_DEFINE_PROVIDER . Манифест не обязательно должен включать <event> определения или <template> , так как события TraceLogging являются самоописывающими.
В процессе сборки компонента используйте компилятор сообщений (MC.exe) из Windows SDK 10.0.22621 или более поздней версии для компиляции манифеста. При этом будут создаваться следующие файлы:
- ManifestName.h: заголовок C/C++, содержащий определения констант. Это позволит определить ChannelSymbol и константы ChannelSymbol_KEYWORD , которые необходимо будет использовать в событиях TraceLogging. (Фактические имена констант будут отличаться для каждого канала.)
- ManifestName.rc: скрипт компилятора ресурсов (RC.exe), который добавляет данные BIN манифеста в двоичный файл (EXE, DLL или SYS). Этот скрипт ресурсов необходимо включить в ресурсы одного из двоичных файлов в компоненте.
- ManifestNameTEMP.BIN, MSG00001.bin: манифест данных BIN, на которые ссылается ManifestName.rc.
#include созданный ManifestName.h файл в коде, который должен создавать события TraceLogging. При этом будут определены константы ChannelSymbol и ChannelSymbol_KEYWORD .
- Если вы указали атрибут symbol в определении <channel> или <importChannel> в манифесте, имя ChannelSymbol будет значением атрибута символа . В противном случае ChannelSymbol будет ProviderSymbol_CHANNEL_ChannelName (т. е. он будет использовать символ из вашего <provider> элемента и имя из элемента <channel> или <importChannel> ).
- Имя ChannelSymbol_KEYWORD — это имя ChannelSymbol, за которым следует _KEYWORD.
- Константой ChannelSymbol_KEYWORD является MC.exe только 10.0.22621 или более поздней версии.
Каждое событие TraceLogging, которое должно перейти в журнал событий, должно использоватьTraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD), чтобы задать канал и ключевое слово для события. Например, если символ канала — MY_CHANNEL, я добавлю в TraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD) качестве параметров макрос TraceLoggingWrite для события.
Чтобы журнал событий распознал поставщика, сведения из манифеста должны быть включены в ресурсы модуля (DLL, EXE или SYS-файл), который будет установлен в целевой системе.
Чтобы журнал событий получал события от поставщика, необходимо зарегистрировать манифест в целевой системе с помощью wevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll во время установки компонента. Кроме того, необходимо отменить регистрацию манифеста с помощью wevtutil um ManifestFile.man во время удаления компонента.

Важно!

Если поставщик зарегистрирован в журнале событий, все события, созданные поставщиком, должны иметь ненулевое ключевое слово, указанное параметром TraceLoggingKeyword, даже если событие не предназначено для журнала событий. События с ключевое слово 0 не могут эффективно фильтроваться и будут доставлены в журнал событий только для удаления. Если журнал событий прослушивает события от поставщика, любое событие с ключевым словом 0 неоправданно увеличит затраты на журнал событий.

Пример события TraceLogging для журнала событий:

TraceLoggingWrite(
    g_hMyProvider,
    "MyWarningEventName",
    TraceLoggingChannel(MY_CHANNEL),         // constant from the MC-generated header
    TraceLoggingKeyword(MY_CHANNEL_KEYWORD), // constant from the MC-generated header
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyEventCategories), // Additional keywords are ok.
    TraceLoggingHResult(errorCode, "Error"));

При необходимости к событиям можно добавить дополнительные ключевые слова, заданные пользователем, с помощью нескольких аргументов TraceLoggingKeyword или путем указания нескольких ключевых слов в одном аргументе TraceLoggingKeyword , например TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD).

Требования

Требование	Значение
Минимальная версия клиента	Windows 10 [только классические приложения]
Минимальная версия сервера	Windows Server 2012 R2
Целевая платформа	Windows
Header	traceloggingprovider.h

См. также раздел

EVENT_DESCRIPTOR

TraceLoggingWrite

Макросы-оболочки TraceLogging

Поделиться через