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

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

  • Статья

Макросы TraceLoggingWrite и TraceLoggingWriteActivity создают события TraceLogging, настроенные в соответствии с параметрами макроса. Каждый из этих макросов принимает набор обязательных параметров, за которым следует до 99 необязательных параметров. Каждый необязательный параметр настраивает событие или добавляет поле в событие. Каждый необязательный параметр должен быть одним из макросов оболочки 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.

В этом примере g_hProvider и "MyEvent1" являются обязательными параметрами. Они указывают поставщика, который будет использоваться для события и имени события. Каждый из оставшихся параметров является макросом-оболочкой. Параметры TraceLoggingLevel и TraceLoggingKeyword настраивают событие. Параметры TraceLoggingString и TraceLoggingHResult добавляют поля в событие.

Макросы конфигурации событий

Следующие макросы настраивают событие.

Если в TraceLoggingWriteне указан определенный макрос конфигурации, для этого события используется значение по умолчанию. Например, если для события не используется параметр TraceLoggingLevel TraceLoggingLevel, событие использует уровень по умолчанию 5 (VERBOSE).

  • TraceLoggingLevel задает уровень события. Уровень — это 8-разрядное значение, указывающее уровень серьезности событий. Уровни от 1 (WINEVENT_LEVEL_CRITICAL) до 5 (WINEVENT_LEVEL_VERBOSE) определяются в <winmeta.h>. Если это не указано, событие по умолчанию соответствует уровню 5 (VERBOSE). Уровень является важной частью маршрутизации событий и фильтрации событий ETW, поэтому все события должны иметь значимый ненулевой уровень.
  • TraceLoggingKeyword задает ключевое слово события. Ключевое слово — это 64-разрядное значение с каждым битом, указывающим категорию, к которой относится событие. Низкие 48 бит ключевого слова определяются владельцем поставщика, а высокие 16 бит ключевого слова определяются корпорацией Майкрософт. Например, вы можете решить, что все поставщики с именем MyCompany.MyComponent будут использовать ключевое слово 0x1 для обозначения "Сеть". Если это не указано, событие по умолчанию использует ключевое слово 0x0 (Нет). Ключевое слово является важной частью маршрутизации событий ETW и фильтрации, поэтому все события должны иметь понятное ненулевое ключевое слово.
  • TraceLoggingOpcode задает события. Опкод представляет собой 8-разрядное значение, указывающее специальную семантику для события, например, что событие записывает начало (WINEVENT_OPCODE_START) или конец (WINEVENT_OPCODE_STOP) действия etw (группа связанных событий). Если это не указано, событие по умолчанию используется для opcode 0 (WINEVENT_OPCODE_INFO), указывающее, что специальные семантики не требуются.
  • TraceLoggingChannel задает каналасобытия. Канал представляет собой 8-разрядное значение, используемое для различных целей. Если этот параметр не указан, событие по умолчанию использует канал 11 (WINEVENT_CHANNEL_TRACELOGGING). Большинство событий не нужно изменять канал события и не следует использовать TraceLoggingChannel.
  • TraceLoggingEventTag задает тег события. Тег представляет собой 28-разрядное значение с семантикой, определенной поставщиком. Например, поставщик может определить бит тегов 0x1000000, чтобы указать, что событие потенциально содержит личные сведения и должно получать специальное лечение от средств обработки событий для конкретного поставщика. Если тег не указан, по умолчанию используется значение 0.
  • TraceLoggingDescription задает описание события. Описание представляет собой строковый литерал с описанием события, доступным для чтения человеком. Это служит комментарием о назначении события, а описание также записывается в виде заметки в символах отладки компонента (PDB). Если не указано, описание по умолчанию используется для "".
  • TraceLoggingCustomAttribute добавляет заметку "ключ-значение" к символам отладки компонента (PDB).

Макросы полей

TraceLogging поддерживает множество макросов оболочки для добавления полей в событие. Каждое поле — это пара "имя-значение". Например, TraceLoggingInt32(argc, "ArgCount") добавит поле INT32 с именем ArgCount со значением argc.

Большинство макросов оболочки полей принимают аналогичные параметры:

  • значение: выражение, которое будет оцениваться во время выполнения, чтобы определить данные, которые необходимо включить в поле. Большинство макросов оболочки полей используют один параметр для указания значения, но для некоторых макросов требуется несколько параметров для значения поля, например указателя и длины. Всегда требуются параметры значений.
    • В некоторых случаях значение поля указывается как pszValue, в этом случае это указатель на 0-прерванную строку символов, включаемую в поле. pszValue может иметь значение NULL, в этом случае значение поля будет пустой строкой "".
    • В некоторых случаях значение поля указывается как pchValue, в этом случае это указатель на строку cchValue символов, которые необходимо включить в поле. pchValue может иметь значение NULL, только если cchValue равно 0.
    • В некоторых случаях значение поля указывается как pValue с автоматически определенным размером (без параметра cbValue cbValue), в этом случае это указатель на значение для включения в поле. pValue не может иметь значение NULL.
    • В некоторых случаях значение поля указывается как pValue с параметром cbValue cbValue, чтобы указать размер (в байтах) данных для включения в поле. pValue может иметь значение NULL, только если cbValue равно 0.
  • имя: строковый литерал (константа времени компиляции) с именем, используемым для поля. Большинство макросов оболочки полей не требуют параметра имени. Если параметр имени не указан, имя поля определяется на основе текста препроцессора значения макроса, pszValue, pchValueили параметра pValue. Например, TraceLoggingInt32(x[4] + y) эквивалентен TraceLoggingInt32(x[4] + y, "x[4] + y"). Оба будут добавлять поле с именем "x[4] + y" в событие со значением, определенным путем оценки выражения x[4] + y.
  • описание: строковый литерал (константа времени компиляции) с описанием, используемым для поля. В основном это удобное место для размещения комментариев для поля, но описание также записывается в виде заметки в символах отладки компонента (PDB). Описание является необязательным. Если параметр описания опущен, описание поля по умолчанию используется для "".
  • тег : 28-разрядное целое число (константа времени компиляции) с семантикой, определяемой поставщиком. Например, поставщик может определить тег 0x2, чтобы указать, что поле содержит номер телефона и должно получать специальное лечение от средств обработки событий для конкретного поставщика. Если параметр тега опущен, тег поля по умолчанию имеет значение 0.

Например, все вызовы макросов оболочки имеют одинаковый эффект:

  • TraceLoggingInt32(argc)
  • TraceLoggingInt32(argc, "argc")
  • TraceLoggingInt32(argc, "argc", "")
  • TraceLoggingInt32(argc, "argc", "", 0)

Скалярами

  • TraceLoggingValue(value, [name, ...]):

    Добавляет поле с типом, который автоматически выводится из типа параметра значения. (только C++)

  • TraceLoggingInt8(value, [name, ...]):

    Добавляет поле со значением INT8.

  • TraceLoggingUInt8(value, [name, ...]):

    Добавляет поле со значением UINT8.

  • TraceLoggingInt16(value, [name, ...]):

    Добавляет поле со значением INT16.

  • TraceLoggingUInt16(value, [name, ...]):

    Добавляет поле со значением UINT16.

  • TraceLoggingInt32(value, [name, ...]):

    Добавляет поле со значением INT32.

  • TraceLoggingUInt32(value, [name, ...]):

    Добавляет поле со значением UINT32.

  • TraceLoggingInt64(value, [name, ...]):

    Добавляет поле со значением INT64.

  • TraceLoggingUInt64(value, [name, ...]):

    Добавляет поле со значением UINT64.

  • TraceLoggingIntPtr(value, [name, ...]):

    Добавляет поле со значением INT_PTR (целое число со знаком с таким же размером, что и указатель).

  • TraceLoggingUIntPtr(value, [name, ...]):

    Добавляет поле со значением UINT_PTR (целое число без знака с таким же размером, что и указатель).

  • TraceLoggingLong(value, [name, ...]):

    Добавляет поле со значением LONG (со знаком long int, 32-разрядные на платформах Windows).

  • TraceLoggingULong(value, [name, ...]):

    Добавляет поле со значением ULONG (без знака длинной int, 32-разрядной версии на платформах Windows).

  • TraceLoggingHexInt8(value, [name, ...]):

    Добавляет поле со значением INT8 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexUInt8(value, [name, ...]):

    Добавляет поле со значением UINT8 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexInt16(value, [name, ...]):

    Добавляет поле со значением INT16 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexUInt16(value, [name, ...]):

    Добавляет поле со значением UINT16 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexInt32(value, [name, ...]):

    Добавляет поле со значением INT32 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexUInt32(value, [name, ...]):

    Добавляет поле со значением UINT32 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexInt64(value, [name, ...]):

    Добавляет поле со значением INT64 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexUInt64(value, [name, ...]):

    Добавляет поле со значением UINT64 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexIntPtr(value, [name, ...]):

    Добавляет поле со значением INT_PTR с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexUIntPtr(value, [name, ...]):

    Добавляет поле со значением UINT_PTR с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexLong(value, [name, ...]):

    Добавляет поле со значением LONG с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexULong(value, [name, ...]):

    Добавляет поле со значением ULONG с шестнадцатеричным указанием форматирования.

  • TraceLoggingFloat32(value, [name, ...]):

    Добавляет поле со значением FLOAT (32-разрядная плавающая точка).

  • TraceLoggingFloat64(value, [name, ...]):

    Добавляет поле со значением DOUBLE (64-разрядная плавающая точка).

  • TraceLoggingBoolean(value, [name, ...]):

    Добавляет поле с 8-разрядным логическим значением (Win32 BOOLEAN или C++ bool).

  • TraceLoggingBool(value, [name, ...]):

    Добавляет поле с 32-разрядным логическим значением (Win32 BOOL).

  • TraceLoggingChar(value, [name, ...]):

    Добавляет поле со значением char (8-разрядное целое число со строковым указанием форматирования, которое обычно рассматривается как кодовая страница 1252).

  • TraceLoggingChar16(value, [name, ...]):

    Добавляет поле со значением char16_t (16-разрядное целое число с указанием форматирования строк, которое обычно рассматривается как UCS-2).

  • TraceLoggingWChar(value, [name, ...]):

    Добавляет поле со значением wchar_t (так же, как char16_t на платформах Windows).

  • TraceLoggingPointer(value, [name, ...]):

    Добавляет поле со значением void* (значением размера указателя с шестнадцатеричным указанием форматирования).

  • TraceLoggingCodePointer(value, [name, ...]):

    Добавляет поле со значением void* (значение размера указателя с указанием форматирования указателя кода).

  • TraceLoggingPid(value, [name, ...]):

    Добавляет поле со значением INT32 с указанием форматирования идентификатора процесса.

  • TraceLoggingTid(value, [name, ...]):

    Добавляет поле со значением INT32 с указанием форматирования идентификатора потока.

  • TraceLoggingIPv4Address(value, [name, ...]):

    Добавляет поле со значением UINT32 с указанием форматирования IPv4 (порядок байтов сети).

  • TraceLoggingIPv6Address(pValue, [имя, ...]):

    Добавляет поле с 16-байтовым двоичным значением с указанием форматирования IPv6.

  • TraceLoggingPort(value, [name, ...]):

    Добавляет поле со значением UINT16 с указанием форматирования IP-портов (порядок сетевых байтов).

  • TraceLoggingSocketAddress(pValue, cbValue, [name, ...]):

    Добавляет поле со значением SOCKADDR.

  • TraceLoggingWinError(value, [name, ...]):

    Добавляет поле со значением UINT32 с указанием форматирования кода ошибки Win32.

  • TraceLoggingNTStatus(value, [name, ...]):

    Добавляет поле со значением NTSTATUS (LONG) с указанием форматирования кода ошибки WinNT.

  • TraceLoggingHResult(value, [name, ...]):

    Добавляет поле со значением HRESULT (LONG) с указанием форматирования Windows HRESULT.

  • TraceLoggingFileTime(value, [name, ...]):

    Добавляет поле со значением FILETIME. При использовании в коде C параметр value должен быть выражением lvalue.

  • TraceLoggingFileTimeUtc(value, [name, ...]):

    Добавляет поле со значением FILETIME с указанием форматирования часового пояса UTC. При использовании в коде C параметр value должен быть выражением lvalue.

  • TraceLoggingSystemTime(value, [name, ...]):

    Добавляет поле со значением SYSTEMTIME. При использовании в коде C параметр value должен быть выражением lvalue.

  • TraceLoggingSystemTimeUtc(value, [name, ...]):

    Добавляет поле со значением SYSTEMTIME с указанием форматирования часового пояса UTC. При использовании в коде C параметр value должен быть выражением lvalue.

  • TraceLoggingGuid(value, [name, ...]):

    Добавляет поле со значением GUID. При использовании в коде C параметр value должен быть выражением lvalue.

  • TraceLoggingString(pszValue, [имя, ...]):

    Добавляет поле с строкой char 0 (обычно рассматривается как кодовая страница 1252). Если значение pszValue равно NULL, в качестве значения поля используется пустая строка "".

  • TraceLoggingUtf8String(pszValue, [имя, ...]):

    Добавляет поле с 0-завершенной строкой char с указанием форматирования UTF-8. Если значение pszValue равно NULL, в качестве значения поля используется пустая строка "".

  • TraceLoggingStringString16(pszValue, [имя, ...]):

    Добавляет поле с 0-завершенной строкой char16_t (UTF-16). Если значение pszValue равно NULL, в качестве значения поля используется пустая строка u"".

  • TraceLoggingWideString(pszValue, [имя, ...]):

    Добавляет поле с строкой wchar_t 0 (UTF-16 в Windows). Если значение pszValue равно NULL, в качестве значения поля используется пустая строка L"".

  • TraceLoggingCountedString(pchValue, cchValue, [имя, ...]):

    Добавляет поле с подсчитаной строкой char (обычно рассматривается как кодовая страница 1252). pchValue может иметь значение NULL, только если cchValue равно 0.

  • TraceLoggingCountedUtf8String(pchValue, cchValue, [имя, описание, тег]):

    Добавляет поле с подсчитаной строкой char с указанием форматирования UTF-8. pchValue может иметь значение NULL, только если cchValue равно 0.

  • TraceLoggingCountedString16(pchValue, cchValue, [имя, ...]):

    Добавляет поле с подсчитаной строкой char16_t (UTF-16). pchValue может иметь значение NULL, только если cchValue равно 0.

  • TraceLoggingCountedWideString(pchValue, cchValue, [имя, описание, тег]):

    Добавляет поле с подсчитываемой строкой wchar_t (UTF-16 в Windows). pchValue может иметь значение NULL, только если cchValue равно 0.

  • TraceLoggingAnsiString(pValue, [name, ...]):

    Добавляет поле со значением ANSI_STRING. Указатель pValue не должен иметь значение NULL.

  • TraceLoggingUnicodeString(pValue, [имя, ...]):

    Добавляет поле со значением UNICODE_STRING. Указатель pValue не должен иметь значение NULL.

  • TraceLoggingSid(pValue, [имя, ...]):

    Добавляет поле со значением идентификатора безопасности. Указатель pValue не должен иметь значение NULL и должен указывать на правильно инициализированный идентификатор БЕЗОПАСНОСТИ (значение редакции и subAuthorityCount должно быть допустимым).

  • TraceLoggingBinary(pValue, cbValue, [name, ...]):

    Добавляет поле с двоичными данными.

  • TraceLoggingBinaryEx(pValue, cbValue, outType, [name, ...]):

    Добавляет поле с двоичными данными с указанием форматирования, указанным outType.

  • TraceLoggingBinaryBuffer(pValue, StructType, [имя, ...]):

    Добавляет поле с двоичными данными. pValue должен быть указателем, отличным от NULL, к структуре StructType. pValue->Buffer должен указывать на начало данных и pValue->Length должно быть число байтов данных, которые должны быть включены в поле.

  • TraceLoggingBinaryBufferEx(pValue, StructType, outType, name, description, tag):

    Добавляет поле с двоичными данными с указанием форматирования, указанным outType. pValue должен быть указателем, отличным от NULL, к структуре StructType. pValue->Buffer должен указывать на начало данных и pValue->Length должно быть число байтов данных, которые должны быть включены в поле.

  • TraceLoggingCustom(pValue, cbValue, protocol, bSchema, cbSchema, [name, ...]):

    Добавляет поле с двоичными данными, сериализованными в соответствии с протоколом сериализации. Сведения о декодировании констант во время компиляции будут включены вместе с событием, чтобы разрешить десериализацию десериализатором событий.

Структуры

Для создания именованной структуры (группы полей) можно использоватьмакросTraceLoggingStruct(fieldCount, name, [...]). Параметр fieldCount указывает, сколько из последующих полей должно считаться частью структуры. Структуры могут быть вложены, в этом случае каждая вложенная структура и его содержащиеся поля считаются одним полем для определения родительской структуры.

Массивы

Вы можете создать поле, содержащее массив скалярных (одно) значений. Например, вы добавляете массив идентификаторов GUID в качестве одного поля в событии.

Заметка

Хотя протокол TraceLogging поддерживает массивы всех типов, TraceLoggingProvider.h предоставляет только макросы-оболочки для массивов простых значений, например он предоставляет макросы для массивов INT32 и GUID, но не предоставляет макросы для массивов строк или массивов структур. Можно создать события с массивами сложных значений, маршалинг данных в буфер, а затем с помощью макросов TraceLoggingPacked, описанных ниже.

TraceLogging поддерживает массивы фиксированной длины и переменной длины.

  • Используйте макрос Array в случаях, когда длина массива не известна во время компиляции и может отличаться при каждом создании события.
  • Используйте макрос FixedArray в случаях, когда длина массива известна во время компиляции (т. е. если длина массива является константой). Это сообщает потребителю событий, что все события с определенным именем события будут иметь одинаковое количество элементов в поле массива.

Для всех макросов массива требуется указывать параметры pValues и cValues с pValues указывая на начало содержимого массива и cValues задать количество элементов в массиве. pValues может иметь значение NULL, только если cValues равно 0.

Все макросы массива при необходимости принимают имя, описаниеи тег, как описано для макросов Scalar. Если имя не указано, имя поля определяется из текста препроцессора pValues. Если описание не указано, описание поля будет "". Если тег не указан, тег поля будет 0.

Заметка

Чтобы убедиться, что трассировка событий не удаляет события, избегайте создания событий с большими массивами. ETW не поддерживает события, размер которых превышает 64 КБ. Любые такие события будут автоматически удалены ETW. Кроме того, события, превышающие буферизации буфер изации клиента, также будут удалены с помощью ETW. Размер события основан на сумме заголовков события, метаданных (поставщик, имена событий и имен полей) и данных (значения полей).

  • TraceLoggingInt8Array(pValues, cValues, [name, ...])
  • TraceLoggingInt8FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUInt8Array(pValues, cValues, [name, ...])
  • TraceLoggingUInt8FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingInt16Array(pValues, cValues, [name, ...])
  • TraceLoggingInt16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUInt16Array(pValues, cValues, [name, ...])
  • TraceLoggingUInt16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingInt32Array(pValues, cValues, [name, ...])
  • TraceLoggingInt32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUInt32Array(pValues, cValues, [name, ...])
  • TraceLoggingUInt32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingInt64Array(pValues, cValues, [name, ...])
  • TraceLoggingInt64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUInt64Array(pValues, cValues, [name, ...])
  • TraceLoggingUInt64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingIntPtrArray(pValues, cValues, [name, ...])
  • TraceLoggingIntPtrFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUIntPtrArray(pValues, cValues, [name, ...])
  • TraceLoggingUIntPtrFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingLongArray(pValues, cValues, [name, ...])
  • TraceLoggingLongFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingULongArray(pValues, cValues, [name, ...])
  • TraceLoggingULongFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexInt8Array(pValues, cValues, [name, ...])
  • TraceLoggingHexInt8FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt8Array(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt8FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexInt16Array(pValues, cValues, [name, ...])
  • TraceLoggingHexInt16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt16Array(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexInt32Array(pValues, cValues, [name, ...])
  • TraceLoggingHexInt32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt32Array(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexInt64Array(pValues, cValues, [name, ...])
  • TraceLoggingHexInt64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt64Array(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexIntPtrArray(pValues, cValues, [name, ...])
  • TraceLoggingHexIntPtrFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUIntPtrArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUIntPtrFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexLongArray(pValues, cValues, [name, ...])
  • TraceLoggingHexLongFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexULongArray(pValues, cValues, [name, ...])
  • TraceLoggingHexULongFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingFloat32Array(pValues, cValues, [name, ...])
  • TraceLoggingFloat32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingFloat64Array(pValues, cValues, [name, ...])
  • TraceLoggingFloat64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingBooleanArray(pValues, cValues, [name, ...])
  • TraceLoggingBooleanFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingBoolArray(pValues, cValues, [name, ...])
  • TraceLoggingBoolFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingCharArray(pValues, cValues, [name, ...])
  • TraceLoggingCharFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingChar16Array(pValues, cValues, [name, ...])
  • TraceLoggingChar16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingWCharArray(pValues, cValues, [name, ...])
  • TraceLoggingWCharFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingPointerArray(pValues, cValues, [name, ...])
  • TraceLoggingPointerFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingCodePointerArray(pValues, cValues, [name, ...])
  • TraceLoggingCodePointerFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingFileTimeArray(pValues, cValues, [name, ...])
  • TraceLoggingFileTimeFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingFileTimeUtcArray(pValues, cValues, [name, ...])
  • TraceLoggingFileTimeUtcFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingSystemTimeArray(pValues, cValues, [name, ...])
  • TraceLoggingSystemTimeFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingSystemTimeUtcArray(pValues, cValues, [name, ...])
  • TraceLoggingSystemTimeUtcFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingGuidArray(pValues, cValues, [name, ...])
  • TraceLoggingGuidFixedArray(pValues, cValues, [name, ...])

Упакованные макросы

TraceLoggingProvider.h предоставляет только макросы полей для типов полей, т. е. полей, в которых каждый макрос поля соответствует одному полю и отдельному региону памяти со значением поля.

TraceLoggingProvider.h не обеспечивает прямую поддержку более сложных случаев, таких как:

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

Для поддержки этих сценариев TraceLoggingProvider.h определяет несколько макросов TraceLoggingPacked, которые позволяют напрямую управлять определением события (метаданными) и значениями полей (данными) события.

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

Макросы TraceLoggingPacked сложно использовать правильно и требуют хорошего понимания того, как создаются события TraceLogging. Если они используются неправильно, это приведет к повреждению событий, которые не декодируются правильно.

Дополнительные сведения об использовании этих макросов см. в комментариях в заголовке TraceLoggingProvider.h.

  • TraceLoggingPackedField(pValue, cbValue, inType, [имя, описание, теги]):

    Добавляет данные поля (pValue, cbValue) и метаданные поля (имя, inType).

  • TraceLoggingPackedFieldEx(pValue, cbValue, inType, outType, [name, ...]):

    Добавляет данные поля (pValue, cbValue) и метаданные поля (имя, inType) вместе с указанием форматирования (outType).

  • TraceLoggingPackedMetadata(inType, [имя, ...]):

    Добавляет метаданные поля (имя, inType) без добавления данных поля. Соответствующие данные поля необходимо добавить с помощью TraceLoggingPackedData.

  • TraceLoggingPackedMetadataEx(inType, outType, [name, ...]):

    Добавляет метаданные поля (имя, inType) и указание форматирования (outType) без добавления данных поля. Соответствующие данные поля необходимо добавить с помощью TraceLoggingPackedData.

  • TraceLoggingPackedStruct(fieldCount, name, [...]):

    Добавляет метаданные поля (имя, полеCount) для структуры.

  • TraceLoggingPackedStructArray(fieldCount, [name, ...]):

    Добавляет метаданные поля (имя, полеCount) для массива структуры переменной длины. Длина массива должна быть указана с помощью TraceLoggingPackedData.

  • TraceLoggingPackedData(pValue, cbValue):

    Добавляет данные поля в событие без добавления метаданных поля. Соответствующие метаданные необходимо добавить с помощью макросов метаданных.

  • TraceLoggingPackedDataEx(pValue, cbValue, dataDescType):

    Добавляет данные поля в событие без добавления метаданных поля, используя определенную Type в EVENT_DATA_DESCRIPTOR данных. Соответствующие метаданные необходимо добавить с помощью макросов метаданных.