TraceLoggingWriteActivity 宏 (traceloggingprovider.h)
发出具有指定活动 ID 的 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
事件的活动 ID，或使用默认值的 NULL。
[in, optional] pRelatedActivityId
事件的相关活动 ID;对于没有相关活动 ID，则为 NULL。
[in, optional] __VA_ARGS__
最多 99 个用于配置或向事件添加字段的其他参数。 每个参数必须是 TraceLogging Wrapper 宏之一，例如 TraceLoggingLevel、 TraceLoggingKeyword 或 TraceLoggingValue。
重要
ProviderId、Level 和 Keyword 是筛选事件的主要方式。 可以进行其他类型的筛选，但开销要高得多。 始终为每个事件分配非零级别和关键字 (keyword) 。
返回值
无
备注
TraceLoggingWriteActivity 宏的每次调用都会扩展到通过指定的提供程序句柄将事件写入 ETW 所需的代码。
- TraceLoggingWriteActivity 检查指定的提供程序是否已注册。 如果未 注册提供程序， 则 TraceLoggingWriteActivity 不执行任何操作。
- TraceLoggingWriteActivity 检查是否有任何使用者正在侦听事件，就像通过调用 TraceLoggingProviderEnabled 一样。 如果没有使用者侦听事件， TraceLoggingWriteActivity 不执行任何工作。
- 否则， TraceLoggingWriteActivity 将计算参数中指定的运行时表达式，保存结果，将必要的数据打包到事件中，并调用 EventWriteTransfer 将事件发送到 ETW。
生成的事件将按如下方式构造：
- 事件的提供程序 ID、提供程序名称和提供程序组将来自 hProvider 参数。
- 事件的名称将来自 eventName 参数。
- 事件的活动 ID 将来自 pActivityId 参数。 如果 pActivityId 为 NULL，则用户模式事件将使用线程的隐式活动 ID，内核模式事件将使用GUID_NULL。
- 事件的相关活动 ID 将来自 pRelatedActivityId 参数。 如果 pRelatedActivityId 为 NULL，则事件将没有相关的活动 ID。
- 事件的级别将来自 TraceLoggingLevel 参数。 如果没有 TraceLoggingLevel 参数，则事件的级别将为 5 (WINEVENT_LEVEL_VERBOSE) 。 如果存在多个 TraceLoggingLevel 参数，则将使用最后一个参数。 若要启用有效的事件筛选，请始终为每个事件分配有意义的非零级别。
- 事件的关键字 (keyword) 将来自 TraceLoggingKeyword 参数。 如果没有 TraceLoggingKeyword 参数，则事件的关键字 (keyword) 将为 0 (NONE) 。 如果存在多个 TraceLoggingKeyword 参数，则这些值将 OR 组合在一起。 若要启用有效的事件筛选，请始终为每个事件分配有意义的非零关键字 (keyword) 。
- 其他事件属性可由 TraceLoggingOpcode、 TraceLoggingDescription、 TraceLoggingEventTag 或 TraceLoggingChannel 等参数设置。
- 可以使用 TraceLoggingStruct 对事件字段进行分组。
- 事件字段由字段参数添加，如 TraceLoggingValue、TraceLoggingInt32、TraceLoggingHResult、TraceLoggingString 等。有关详细信息 ，请参阅 TraceLogging Wrapper 宏 。
例如：
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。 ETW 接受的描述符的最大数目为 128。 由于每个参数可能需要使用 0、1 或 2 个描述符，因此在达到参数限制 (99) 之前，可能会达到数据描述符限制 (128) 。
重要
尽量避免大型事件。 ETW 主要用于处理小型事件。 TraceLoggingWriteActivity 将以无提示方式删除任何太大的事件。 事件的大小基于 ETW 运行时) (添加的事件标头总数，元数据 (即提供程序名称、事件名称、字段名称、字段类型) 以及数据 (字段值) 。 如果事件的总大小大于 65535，或者使用者会话使用的缓冲区大小小于事件的大小，则不会记录事件。
调用 TraceLoggingWrite 与调用 TraceLoggingWriteActivity 相同，pActivityId 和 pRelatedActivityId 参数为 NULL。 如果需要为事件指定活动 ID，请使用 TraceLoggingWriteActivity 。
有关 ActivityId 和 RelatedActivityId 参数的语义的信息，请参阅 EventWriteTransfer。
有关在 ETW 中编写活动的信息 ，请参阅 EventActivityIdControl 。
请参阅用于帮助管理 TraceLogging ETW 活动的 C++ 类的 TraceLoggingActivity。
要求
| 最低受支持的客户端 | Windows Vista [桌面应用 | UWP 应用] |
| 最低受支持的服务器 | Windows Server 2008 [桌面应用 | UWP 应用] |
| 目标平台 | Windows |
| 标头 | traceloggingprovider.h |
| Library | Advapi32.lib |