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

Статья
08/26/2023

Создает событие TraceLogging.

Синтаксис

void TraceLoggingWrite(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  __VA_ARGS__
);

Параметры

[in] hProvider

Дескриптор поставщика TraceLogging , используемый для записи события.

[in] eventName

Короткое и уникальное имя, используемое для идентификации события. Это должен быть строковый литерал, а не переменная. Он не может содержать внедренные '\0' символы.

[in, optional] __VA_ARGS__

До 99 дополнительных параметров для настройки или добавления полей в событие. Каждый параметр должен быть одним из макросов-оболочек TraceLogging, например TraceLoggingLevel, TraceLoggingKeyword или TraceLoggingValue.

Важно!

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

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

None

Remarks

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

TraceLoggingWrite проверяет, зарегистрирован ли указанный поставщик. Если поставщик не зарегистрирован, TraceLoggingWrite ничего не делает.
TraceLoggingWrite проверяет, прослушивает ли какой-либо потребитель событие, как если бы путем вызова TraceLoggingProviderEnabled. Если объект-получатель не прослушивает событие, TraceLoggingWrite не выполняет никаких действий.
В противном случае TraceLoggingWrite вычисляет выражения среды выполнения, указанные в аргументах, сохраняет результаты, упаковывает необходимые данные в событие и вызывает EventWriteTransfer для отправки события в трассировку событий Windows.

Созданное событие будет построено следующим образом:

Идентификатор поставщика события, имя поставщика и группа поставщиков будут поступать из параметра hProvider .
Имя события будет поступать из параметра eventName .
В пользовательском режиме идентификатор действия события будет поступать из неявного идентификатора действия потока. В режиме ядра идентификатор действия события будет GUID_NULL.
Событие не будет иметь связанного идентификатора действия.
Уровень события будет получен из аргумента TraceLoggingLevel . Если аргумент TraceLoggingLevel отсутствует, уровень события будет равен 5 (WINEVENT_LEVEL_VERBOSE). Если имеется несколько аргументов TraceLoggingLevel, будет использоваться последний аргумент. Чтобы включить эффективную фильтрацию событий, всегда назначайте каждому событию значимый уровень, отличный от нуля.
Ключевое слово события будет исходить из аргумента TraceLoggingKeyword. Если аргумент TraceLoggingKeyword отсутствует, ключевое слово события будет равно 0 (NONE). Если имеется несколько аргументов TraceLoggingKeyword, значения будут объединяться в or'ed. Чтобы включить эффективную фильтрацию событий, всегда назначайте каждому событию значимый ненулевой ключевое слово.
Другие атрибуты событий могут задаваться такими аргументами, как TraceLoggingOpcode, TraceLoggingDescription, TraceLoggingEventTag или TraceLoggingChannel.
Поля событий можно сгруппировать с помощью TraceLoggingStruct.
Поля событий добавляются аргументами полей, такими как TraceLoggingValue, TraceLoggingInt32, TraceLoggingHResult, TraceLoggingStringString и т. д. Дополнительные сведения см. в разделе Макросы-оболочки TraceLogging .

Пример:

TraceLoggingWrite(
    g_hProvider,
    "MyEvent1",
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword),
    TraceLoggingString(operationName), // Adds an "operationName" field.
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

TraceLoggingWrite(hProvider, "EventName", args...) Вызов можно рассматривать как расширение до следующего кода:

if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
    static const metadata = { GetMetadataFromArgs(args...) };
    EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
    EventWriteTransfer(etwHandle, metadata.desc, NULL, NULL, N, data);
}

Примечание

Каждый макрос TraceLoggingWrite автоматически проверяет TraceLoggingProviderEnabled , поэтому событие будет записано только в том случае, если потребитель прослушивает события от поставщика. В результате обычно нет необходимости напрямую вызывать TraceLoggingProviderEnabled. Любые выражения среды выполнения в args... будут вычисляться только в том случае, если событие включено. Выражения среды выполнения не будут вычисляться более одного раза.

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

Макрос TraceLoggingWrite использует массив EVENT_DATA_DESCRIPTOR для передачи данных в etw. Максимальное число дескрипторов, принятых трассировой событий Windows, составляет 128. Так как для каждого параметра может потребоваться использовать 0, 1 или 2 дескриптора, можно достичь предела дескриптора данных (128) до достижения ограничения аргументов (99).

Важно!

Старайтесь избегать крупных событий. Трассировка событий Windows в основном предназначена для обработки небольших событий. TraceLoggingWrite автоматически удаляет любое слишком большое событие. Размер события зависит от общего количества заголовков события (добавленных средой выполнения ETW), метаданных (т. е. имени поставщика, имени события, имен полей, типов полей) и данных (значения полей). Если общий размер события больше 65535 или сеанс потребителя использует размер буфера, меньший, чем размер события, событие не будет записано.

Вызов TraceLoggingWrite совпадает с вызовом TraceLoggingWriteActivity с null для параметров pActivityId и pRelatedActivityId . Используйте TraceLoggingWriteActivity , если необходимо указать идентификаторы действий для события.

Примеры

#include <windows.h> // or <wdm.h> for kernel-mode.
#include <winmeta.h> // For event level definitions.
#include <TraceLoggingProvider.h>

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider,  // Name of the provider handle
    "MyProvider", // Human-readable name of the provider
    // ETW Control GUID: {b3864c38-4273-58c5-545b-8b3608343471}
    (0xb3864c38,0x4273,0x58c5,0x54,0x5b,0x8b,0x36,0x08,0x34,0x34,0x71));

int main(int argc, char* argv[]) // or DriverEntry for kernel-mode.
{
    TraceLoggingRegister(g_hProvider);

    TraceLoggingWrite(
        g_hProvider,
        "MyEvent1",
        TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
        TraceLoggingKeyword(MyEventCategories), // Provider-defined categories
        TraceLoggingString(argv[0], "arg0"), // field name is "arg0"
        TraceLoggingInt32(argc)); // field name is implicitly "argc"

    TraceLoggingUnregister(g_hProvider);
    return 0;
}

Требования


Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	traceloggingprovider.h
Библиотека	Advapi32.lib

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

EventWriteTransfer

TraceLoggingWriteActivity

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