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 参数用于事件，则事件使用默认级别 5 (VERBOSE) 。

  • TraceLoggingLevel 设置事件的 级别。 级别是一个 8 位值，指示事件严重性。 在 中定义了从 1 (WINEVENT_LEVEL_CRITICAL) 到 5 (WINEVENT_LEVEL_VERBOSE) 的 <winmeta.h>级别。 如果未指定，事件默认为级别 5， (VERBOSE) 。 级别是 ETW 事件路由和筛选的重要组成部分，因此所有事件都应具有有意义的非零级别。
  • TraceLoggingKeyword 设置事件的关键字 (keyword) 。 关键字 (keyword) 是一个 64 位值，每个位指示事件所属的类别。 关键字 (keyword) 的低 48 位由提供程序的所有者定义，而关键字 (keyword) 的高 16 位由 Microsoft 定义。 例如，可以决定名称为“MyCompany.MyComponent”的所有提供程序都将使用 关键字 (keyword) 0x1 表示“网络”。 如果未指定，事件默认关键字 (keyword) 0x0 (None) 。 关键字是 ETW 事件路由和筛选的重要组成部分，因此所有事件都应具有有意义的非零关键字 (keyword) 。
  • TraceLoggingOpcode 设置事件的 操作码。 opcode 是一个 8 位值，指示事件的特殊语义，例如，事件记录 ETW 活动的 开始 (WINEVENT_OPCODE_START) 或结束 (WINEVENT_OPCODE_STOP) (一组相关事件) 。 如果未指定，事件默认为 opcode 0 (WINEVENT_OPCODE_INFO) 指示不需要特殊语义。
  • TraceLoggingChannel 设置事件的 通道。 通道是用于各种目的的 8 位值。 如果未指定，事件默认为通道 11 (WINEVENT_CHANNEL_TRACELOGGING) 。 大多数事件不需要更改事件的通道，也不应使用 TraceLoggingChannel。
  • TraceLoggingEventTag 设置事件的 标记。 标记是具有提供程序定义的语义的 28 位值。 例如，提供程序可以定义标记位0x1000000，以指示事件可能包含个人身份信息，并且应从特定于提供程序的事件处理工具接收特殊处理。 如果未指定，标记默认为 0。
  • TraceLoggingDescription 设置事件的说明。 说明是一个字符串文本，其中包含事件可读的描述。 这用作有关事件目的的注释，并且说明也作为注释记录在组件的调试符号 (PDB) 。 如果未指定，说明默认为 ""。
  • TraceLoggingCustomAttribute 将键值批注添加到组件的调试符号 (PDB) 。

字段宏

TraceLogging 支持许多包装宏，用于向事件添加字段。 每个字段都是一个名称/值对。 例如， TraceLoggingInt32(argc, "ArgCount") 将添加一个名为“ArgCount”的 INT32 字段，其值为 argc。

大多数字段包装宏接受类似的参数：

  • 价值： 将在运行时计算的表达式，以确定要包含在字段中的数据。 大多数字段包装宏使用单个参数来指定值，但某些宏需要多个参数来指定字段值，例如指针和长度。 始终需要值参数 () 。
    • 在某些情况下，字段值指定为 pszValue，在这种情况下，它是指向要包括在字段中的以 0 结尾的字符串的指针。 pszValue 可以为 NULL，在这种情况下，字段值为空字符串 ""。
    • 在某些情况下，字段值指定为 pchValue，在这种情况下，它是指向要包含在字段中的 cchValue 字符字符串的指针。 仅当 cchValue 为 0 时，pchValue 才可为 NULL。
    • 在某些情况下，字段值指定为 pValue ，具有自动确定的大小 (没有 cbValue 参数) ，在这种情况下，它是指向要包含在字段中的值的指针。 pValue 可能不为 NULL。
    • 在某些情况下，字段值指定为具有 cbValue 参数的 pValue，以指定要包含在字段中的数据) 的大小 (字节数。 仅当 cbValue 为 0 时，pValue 才可为 NULL。
  • 名字： 字符串文本 (编译时常量) ，其中包含要用于字段的名称。 大多数字段包装宏不需要 name 参数。 如果省略 name 参数，则根据宏 值pszValue、 pchValue 或 pValue 参数的预处理器文本确定字段的名称。 例如，TraceLoggingInt32(x[4] + y) 等效于 TraceLoggingInt32(x[4] + y, "x[4] + y")。 两者都会向事件添加一个名为 "x[4] + y" 的字段，其中包含通过计算表达式 x[4] + y确定的值。
  • 描述： 字符串文本 (编译时常量) ，其中包含要用于字段的说明。 这主要用作为字段添加注释的方便位置，但说明也作为注释记录在组件的调试符号 (PDB) 。 说明是可选的。 如果省略 description 参数，则字段的说明默认为 ""。
  • 标记： 28 位整数 (具有提供程序定义的语义的编译时常量) 。 例如，提供商可以定义标记0x2，以指示字段包含电话号码，并且应从特定于提供程序的事件处理工具接收特殊处理。 如果省略标记参数，则字段的标记默认为 0。

例如，以下包装器宏调用具有相同的效果：

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

标量

  • TraceLoggingValue (值 [name， ...]) ：

    添加一个字段，该字段具有从值参数的类型自动推导的类型。 仅) (C++

  • TraceLoggingInt8 (值 [name， ...]) ：

    添加具有 INT8 值的字段。

  • TraceLoggingUInt8 (值 [name， ...]) ：

    添加具有 UINT8 值的字段。

  • TraceLoggingInt16 (值 [name， ...]) ：

    添加具有 INT16 值的字段。

  • TraceLoggingUInt16 (值 [name， ...]) ：

    添加具有 UINT16 值的字段。

  • TraceLoggingInt32 (值 [name， ...]) ：

    添加具有 INT32 值的字段。

  • TraceLoggingUInt32 (值 [name， ...]) ：

    添加具有 UINT32 值的字段。

  • TraceLoggingInt64 (值 [name， ...]) ：

    添加具有 INT64 值的字段。

  • TraceLoggingUInt64 (值 [name， ...]) ：

    添加具有 UINT64 值的字段。

  • TraceLoggingIntPtr (值 [name， ...]) ：

    将具有INT_PTR值的字段添加到与指针) 大小相同的带符号整数 (。

  • TraceLoggingUIntPtr (值 [name， ...]) ：

    将具有UINT_PTR值的字段添加到与指针) 大小相同的无符号整数 (。

  • TraceLoggingLong (值 [name， ...]) ：

    在 Windows 平台上添加一个具有 LONG 值的字段， (32 位的有符号长 int) 。

  • TraceLoggingULong (值 [name， ...]) ：

    在 Windows 平台上添加具有 ULONG 值的字段 (无符号长 int、32 位) 。

  • TraceLoggingHexInt8 (值 [name， ...]) ：

    添加具有十六进制格式设置提示的 INT8 值的字段。

  • TraceLoggingHexUInt8 (值 [name， ...]) ：

    添加带有十六进制格式提示的 UINT8 值的字段。

  • TraceLoggingHexInt16 (值 [name， ...]) ：

    添加具有十六进制格式提示的 INT16 值的字段。

  • TraceLoggingHexUInt16 (值 [name， ...]) ：

    添加具有 UINT16 值的字段以及十六进制格式提示。

  • TraceLoggingHexInt32 (值 [name， ...]) ：

    添加具有具有十六进制格式提示的 INT32 值的字段。

  • TraceLoggingHexUInt32 (值 [name， ...]) ：

    添加具有 UINT32 值的字段，其中包含十六进制格式设置提示。

  • TraceLoggingHexInt64 (值 [name， ...]) ：

    添加具有具有十六进制格式提示的 INT64 值的字段。

  • TraceLoggingHexUInt64 (值 [name， ...]) ：

    添加具有 UINT64 值的字段以及十六进制格式设置提示。

  • TraceLoggingHexIntPtr (值 [name， ...]) ：

    添加具有十六进制格式提示的INT_PTR值的字段。

  • TraceLoggingHexUIntPtr (值 [name， ...]) ：

    使用十六进制格式设置提示添加具有UINT_PTR值的字段。

  • TraceLoggingHexLong (值[name， ...]) ：

    添加具有具有十六进制格式提示的 LONG 值的字段。

  • TraceLoggingHexULong (值 [name， ...]) ：

    添加带有十六进制格式设置提示的 ULONG 值的字段。

  • TraceLoggingFloat32 (值 [name， ...]) ：

    添加具有 FLOAT (32 位浮点) 值的字段。

  • TraceLoggingFloat64 (值 [name， ...]) ：

    添加具有 DOUBLE (64 位浮点) 值的字段。

  • TraceLoggingBoolean (值 [name， ...]) ：

    (Win32 BOOLEAN 或 C++ bool) 添加具有 8 位布尔值的字段。

  • TraceLoggingBool (值 [name， ...]) ：

    (Win32) 添加具有 32 BOOL 位布尔值的字段。

  • TraceLoggingChar (值 [name， ...]) ：

    添加值 (具有字符串格式设置提示的 8 位整数的字段 char ，通常被视为代码页 1252) 。

  • TraceLoggingChar16 (值 [name， ...]) ：

    使用字符串格式设置提示添加值 (16 位整数的字段 char16_t ，通常被视为 UCS-2) 。

  • TraceLoggingWChar (值[name， ...]) ：

    添加值 (与 Windows 平台上) 相同的char16_t字段wchar_t。

  • TraceLoggingPointer (值 [name， ...]) ：

    使用十六进制格式提示 (指针大小的值添加一个字段 void*) 。

  • TraceLoggingCodePointer (值 [name， ...]) ：

    使用代码指针格式设置提示 (指针大小的值添加一个字段 void*) 。

  • TraceLoggingPid (值 [name， ...]) ：

    使用进程 ID 格式设置提示添加具有 INT32 值的字段。

  • TraceLoggingTid (值[name， ...]) ：

    添加具有 INT32 值的字段以及线程 ID 格式设置提示。

  • TraceLoggingIPv4Address (值 [name， ...]) ：

    使用 IPv4 格式设置提示 (网络字节顺序) 添加具有 UINT32 值的字段。

  • TraceLoggingIPv6Address (pValue， [name， ...]) ：

    使用 IPv6 格式设置提示添加具有 16 字节二进制值的字段。

  • TraceLoggingPort (值 [name， ...]) ：

    添加具有 UINT16 值的字段，其中包含 IP 端口格式设置提示 (网络字节顺序) 。

  • TraceLoggingSocketAddress (pValue， cbValue， [name， ...]) ：

    添加具有 SOCKADDR 值的字段。

  • TraceLoggingWinError (值 [name， ...]) ：

    添加具有 UINT32 值的字段以及 Win32 错误代码格式设置提示。

  • TraceLoggingNTStatus (值 [name， ...]) ：

    添加具有 NTSTATUS (LONG) 值的字段，并带有 WinNT 错误代码格式设置提示。

  • TraceLoggingHResult (值 [name， ...]) ：

    使用 Windows HRESULT 格式设置提示添加具有 HRESULT (LONG) 值的字段。

  • TraceLoggingFileTime (值 [name， ...]) ：

    添加具有 FILETIME 值的字段。 在 C 代码中使用 时， value 参数必须是左值表达式。

  • TraceLoggingFileTimeUtc (值 [name， ...]) ：

    添加带有 UTC 时区格式设置提示 的 FILETIME 值的字段。 在 C 代码中使用 时， value 参数必须是左值表达式。

  • TraceLoggingSystemTime (值 [name， ...]) ：

    添加具有 SYSTEMTIME 值的字段。 在 C 代码中使用 时， value 参数必须是左值表达式。

  • TraceLoggingSystemTimeUtc (值 [name， ...]) ：

    添加带有 UTC 时区格式设置提示 的 SYSTEMTIME 值的字段。 在 C 代码中使用 时， value 参数必须是左值表达式。

  • TraceLoggingGuid (值 [name， ...]) ：

    添加具有 GUID 值的字段。 在 C 代码中使用 时， value 参数必须是左值表达式。

  • TraceLoggingString (pszValue， [name， ...]) ：

    添加一个以 0 结尾 char 的字符串的字段， (通常被视为代码页 1252) 。 如果 pszValue 为 NULL，则将空字符串 "" 用作字段值。

  • TraceLoggingUtf8String (pszValue， [name， ...]) ：

    使用 UTF-8 格式设置提示添加以 0 结尾 char 的字符串的字段。 如果 pszValue 为 NULL，则将空字符串 "" 用作字段值。

  • TraceLoggingString16 (pszValue， [name， ...]) ：

    (UTF-16) 添加一个以 0 结尾 char16_t 的字符串的字段。 如果 pszValue 为 NULL，则将空字符串 u"" 用作字段值。

  • TraceLoggingWideString (pszValue， [name， ...]) ：

    在 Windows) 上 (UTF-16 添加一个以 0 结尾 wchar_t 的字符串的字段。 如果 pszValue 为 NULL，则将空字符串 L"" 用作字段值。

  • TraceLoggingCountedString (pchValue， cchValue， [name， ...]) ：

    添加一个字段，其中包含计数 char 字符串 (通常被视为代码页 1252) 。 仅当 cchValue 为 0 时，pchValue 才可为 NULL。

  • TraceLoggingCountedUtf8String (pchValue， cchValue， [name， description， tag]) ：

    添加具有 UTF-8 格式提示的 char 计数字符串的字段。 仅当 cchValue 为 0 时，pchValue 才可为 NULL。

  • TraceLoggingCountedString16 (pchValue， cchValue， [name， ...]) ：

    在 UTF-16) (添加包含计数 char16_t 字符串的字段。 仅当 cchValue 为 0 时，pchValue 才可为 NULL。

  • TraceLoggingCountedWideString (pchValue， cchValue， [name， description， tag]) ：

    在 Windows) 上 (UTF-16 添加包含计数 wchar_t 字符串的字段。 仅当 cchValue 为 0 时，pchValue 才可为 NULL。

  • TraceLoggingAnsiString (pValue， [name， ...]) ：

    添加具有 ANSI_STRING 值的字段。 pValue 指针不得为 NULL。

  • TraceLoggingUnicodeString (pValue， [name， ...]) ：

    添加具有 UNICODE_STRING 值的字段。 pValue 指针不得为 NULL。

  • TraceLoggingSid (pValue， [name， ...]) ：

    添加具有 SID 值的字段。 pValue 指针不得为 NULL，并且必须指向正确初始化的 SID (Revision 和 SubAuthorityCount 必须有效) 。

  • TraceLoggingBinary (pValue， cbValue， [name， ...]) ：

    添加包含二进制数据的字段。

  • TraceLoggingBinaryEx (pValue， cbValue， outType， [name， ...]) ：

    使用 指定的 outType格式设置提示添加包含二进制数据的字段。

  • TraceLoggingBinaryBuffer (pValue， StructType， [name， ...]) ：

    添加包含二进制数据的字段。 pValue 必须是指向 StructType 结构的非 NULL 指针。 pValue->Buffer 必须指向数据的开头，并且 pValue->Length 必须是要包含在字段中的数据的字节数。

  • TraceLoggingBinaryBufferEx (pValue， StructType， outType， name， description， tag) ：

    使用 指定的 outType格式设置提示添加包含二进制数据的字段。 pValue 必须是指向 StructType 结构的非 NULL 指针。 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 设置为数组中的项数。 仅当 cValues 为 0 时，pValues 才可为 NULL。

所有数组宏（可选）接受 名称、 说明和 标记 参数，如标量宏所述。 如果未指定 name ，则根据 pValues 的预处理器文本确定字段名称。 如果未指定 description ，则字段说明将为 ""。 如果未指定 标记 ，则字段标记将为 0。

注意

若要确保 ETW 不会删除事件，请避免创建具有大型数组的事件。 ETW 不支持大于 64KB 的事件。 ETW 将以无提示方式删除任何此类事件。 此外，ETW 还会删除大于使用者会话的 BufferSize 的事件。 事件大小基于事件标头、元数据 (提供程序、事件和字段名称) 的总和，以及) 数据 (字段值。

  • 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 仅为 blittable 字段类型提供字段宏，即每个字段宏对应于单个字段和具有字段值的单个连续内存区域。

TraceLoggingProvider.h 不为更复杂的情况提供直接支持，例如：

  • 记录长度可变类型的数组，例如字符串数组。
  • 记录结构的数组。
  • 通过单个缓冲区将多个字段传递给 ETW，以减少事件日志记录开销。

为了支持这些方案，TraceLoggingProvider.h 定义了多个 TraceLoggingPacked 宏，使你能够直接操作事件定义 (元数据) 和字段值 (事件的数据) 。

警告

这些 TraceLoggingPacked 宏很难正确使用，需要深入了解 TraceLogging 事件的创建方式。 如果使用不当，它们将导致损坏事件，这些事件无法正确解码。

有关使用这些宏的详细信息，请参阅 TraceLoggingProvider.h 标头中的注释。

  • TraceLoggingPackedField (pValue， cbValue， inType， [name， description， tags]) ：

    (pValue、cbValue) 和字段元数据添加字段数据， (名称、inType) 。

  • TraceLoggingPackedFieldEx (pValue， cbValue， inType， outType， [name， ...]) ：

    (pValue、cbValue) 和字段元数据 (名称、inType) 以及 (outType) 的格式提示添加字段数据。

  • TraceLoggingPackedMetadata (inType， [name， ...]) ：

    添加字段元数据 (名称，inType) 而不添加字段数据。 必须通过 TraceLoggingPackedData 添加相应的字段数据。

  • TraceLoggingPackedMetadataEx (inType， outType， [name， ...]) ：

    (名称、inType) 和格式设置提示 (outType) 添加字段元数据，而无需添加字段数据。 必须通过 TraceLoggingPackedData 添加相应的字段数据。

  • TraceLoggingPackedStruct (fieldCount， name， [...]) ：

    为结构添加字段元数据 (name、fieldCount) 。

  • TraceLoggingPackedStructArray (fieldCount， [name， ...]) ：

    为可变长度的结构数组添加字段元数据 (name、fieldCount) 。 数组长度必须通过 TraceLoggingPackedData 指定。

  • TraceLoggingPackedData (pValue、cbValue) ：

    将字段数据添加到事件，而不添加任何字段元数据。 必须通过元数据宏添加相应的元数据。

  • TraceLoggingPackedDataEx (pValue、cbValue、dataDescType) ：

    使用数据EVENT_DATA_DESCRIPTOR中的特定 Type ，将字段数据添加到事件而不添加任何字段元数据。 必须通过元数据宏添加相应的元数据。