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

Статья
08/26/2023

Создает событие TraceLogging с указанными идентификаторами действий.

Синтаксис

void TraceLoggingWriteActivity(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  pActivityId,
  [in, optional]  pRelatedActivityId,
  [in, optional]  __VA_ARGS__
);

Параметры

[in] hProvider

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

[in] eventName

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

[in, optional] pActivityId

Идентификатор действия для события или значение NULL для использования значения по умолчанию.

[in, optional] pRelatedActivityId

Идентификатор связанного действия для события или NULL для идентификатора связанного действия.

[in, optional] __VA_ARGS__

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

Важно!

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

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

None

Remarks

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

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

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

Идентификатор поставщика события, имя поставщика и группа поставщиков будут поступать из параметра hProvider .
Имя события будет поступать из параметра eventName .
Идентификатор действия события будет получен из параметра pActivityId . Если pActivityId имеет значение NULL, события пользовательского режима будут использовать неявный идентификатор действия потока, а события режима ядра — GUID_NULL.
Идентификатор связанного действия события будет получен из параметра pRelatedActivityId . Если pRelatedActivityId имеет значение 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 .

Пример:

TraceLoggingWriteActivity(
    g_hProvider,
    "MyEvent1",
    &myActivityGuid,
    NULL, // no related activity ID
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword), // Provider-defined categories
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

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

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

Примечание

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

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

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

Важно!

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

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

Сведения о семантике параметров ActivityId и RelatedActivityId см. в разделе EventWriteTransfer.

Сведения о написании действий в трассировке событий Windows см. в разделе EventActivityIdControl .

См . раздел TraceLoggingActivity для классов C++, которые помогают управлять действиями Трассировки событий Windows TraceLogging.

Требования


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

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

EventActivityIdControl

EventWriteTransfer

TraceLoggingActivity

TraceLoggingWrite

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

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