TraceLogging 包装器宏

TraceLoggingWriteTraceLoggingWriteActivity 宏会发出根据宏参数配置的 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" 必需的参数。 它们指定要用于事件和事件名称的提供程序。 其余每个参数都是包装宏。 和TraceLoggingLevelTraceLoggingKeyword参数配置事件。 参数TraceLoggingStringTraceLoggingHResult将字段添加到事件。

事件配置宏

以下宏配置事件。

如果未在 TraceLoggingWrite 中提供特定配置宏,则默认用于该事件。 例如,如果没有用于事件的 TraceLoggingLevel 参数,该事件将使用默认级别为 5 (VERBOSE) 。

  • TraceLoggingLevel 设置事件的 级别。 级别是一个 8 位值,指示事件严重性。 定义从 1 个 (WINEVENT_LEVEL_CRITICAL) 到 5 个 <winmeta.h> (WINEVENT_LEVEL_VERBOSE) 的级别。 如果未指定,则事件默认为级别 5 (VERBOSE) 。 级别是 ETW 事件路由和筛选的重要组成部分,因此所有事件都应具有有意义的非零级别。
  • TraceLoggingKeyword 设置事件的 关键字。 关键字是一个 64 位值,每个位指示事件所属的类别。 关键字的低 48 位由提供程序的所有者定义,而关键字的高 16 位由 Microsoft 定义。 例如,你可能会确定名称为“MyCompany.MyComponent”的所有提供程序都将使用关键字0x1表示“网络”。 如果未指定,则事件默认为关键字0x0 (None) 。 关键字是 ETW 事件路由和筛选的重要组成部分,因此所有事件都应具有有意义的非零关键字。
  • TraceLoggingOpcode 设置事件的 操作码。 操作码是一个 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”且值为 argc“ArgCount”的 INT32 字段。

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

  • 价值: 将在运行时计算的表达式,用于确定要包括在字段中的数据。 大多数字段包装宏使用单个参数来指定值,但某些宏需要字段值的多个参数,例如指针和长度。 始终需要值参数 (s) 。
    • 在某些情况下,字段值被指定为 pszValue,在这种情况下,它是指向要包含在字段中的 0 终止字符字符串的指针。 pszValue 可以是 NULL,在这种情况下,字段值将是空字符串 ""
    • 在某些情况下,字段值被指定为 pchValue,在这种情况下,它是指向要包含在字段中的 cchValue 字符字符串的指针。 仅当 cchValue 为 0 时,pchValue 可能为 NULL。
    • 在某些情况下,字段值指定为 pValue ,其大小自动确定 (无 cbValue 参数) ,在这种情况下,它是指向要在字段中包含的值的指针。 pValue 可能不是 NULL。
    • 在某些情况下,字段值指定为具有 cbValue 参数的 pValue,以指定要包含在字段中的数据的大小 (以字节为单位) 。 仅当 cbValue 为 0 时,pValue 可能为 NULL。
  • 名字: 字符串文本 (编译时常量) ,该常量的名称用于字段。 大多数字段包装器宏不需要名称参数。 如果省略名称参数,则根据宏 pszValuepchValuepValue 参数的预处理器文本确定字段的名称。 例如,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 (值[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 值的字段 (签名的长 int、32 位。

  • 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 (value, [name, ...]) :

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    使用代码指针格式提示) 添加具有 void* 值 (指针大小的值的字段。

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

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

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

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

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

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

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

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

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

    使用 IP 端口格式提示 (网络字节顺序) 添加具有 UINT16 值的字段。

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

    添加具有 SOCKADDR 值的字段。

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

    使用 Win32 错误代码格式提示添加具有 UINT32 值的字段。

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

    使用 WINNT 错误代码格式提示添加具有 NTSTATUS (LONG) 值的字段。

  • 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) 上添加具有 0 终止 wchar_t 字符串的字段 (UTF-16。 如果 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) 上添加包含计数 wchar_t 字符串 (UTF-16 的字段。 仅当 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 必须是结构的非 NULL 指针 StructTypepValue->Buffer 必须指向数据开头,并且 pValue->Length 必须是字段中要包含的数据字节数。

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

    使用格式 outType设置提示添加具有二进制数据的字段。 pValue 必须是结构的非 NULL 指针 StructTypepValue->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。

所有数组宏(可选)接受标量宏描述 的名称说明标记 参数。 如果未指定 名称 ,则从 pValues 的预处理器文本确定字段名称。 如果未指定 说明 ,则字段说明将为 ""。 如果未指定 标记 ,则字段标记将为 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]) :

    在Type) 中添加字段数据 (pValue、cbValue) 和字段元数据 (名称。

  • 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, ...) :

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

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

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

  • TraceLoggingPackedData (pValue、cbValue) :

    在不添加任何字段元数据的情况下向事件添加字段数据。 必须通过元数据宏添加相应的元数据。

  • TraceLoggingPackedDataEx (pValue、cbValue、dataDescType) :

    使用数据EVENT_DATA_DESCRIPTOR中的特定Type内容,在不添加任何字段元数据的情况下向事件添加字段数据。 必须通过元数据宏添加相应的元数据。