EventActivityIdControl 函数 (evntprov.h)
创建、查询和设置用于 ETW 事件的活动标识符。
语法
ULONG EVNTAPI EventActivityIdControl(
[in] ULONG ControlCode,
[in, out] LPGUID ActivityId
);
参数
[in] ControlCode
一个控件代码,指定要执行的操作。
EVENT_ACTIVITY_CTRL_GET_ID
将 ActivityId 参数设置为当前线程的活动 ID 的值。
EVENT_ACTIVITY_CTRL_SET_ID
将当前线程的活动 ID 设置为 ActivityId 参数的值。
EVENT_ACTIVITY_CTRL_CREATE_ID
将 ActivityId 参数设置为新生成的本地唯一活动 ID 的值。
EVENT_ACTIVITY_CTRL_GET_SET_ID
交换 ActivityId 参数的值和当前线程的活动 ID。 (保存当前线程的活动 ID 的值,然后将当前线程的活动 ID 设置为 ActivityId 参数的值,然后将 ActivityId 参数设置为保存的值。)
EVENT_ACTIVITY_CTRL_CREATE_SET_ID
将 ActivityId 参数设置为当前线程的活动 ID 的值,然后将当前线程的活动 ID 设置为新生成的本地唯一活动 ID 的值。
[in, out] ActivityId
指向包含 128 位活动 ID 的缓冲区的指针。 此缓冲区可以是从中读取和/或写入的,具体取决于 ControlCode 参数的值。
返回值
如果成功,则返回 ERROR_SUCCESS 。
注解
使用 EventWrite API 之一写入的 ETW 事件将包含 128 位“活动 ID”字段,并且可以选择包含 128 位“相关活动 ID”字段。 跟踪处理工具可以使用这些字段的值将事件组织成称为活动的组。
- 活动 ID 为零 ((即 GUID_NULL) )的所有事件都假定不是任何活动的一部分。
- 假定具有特定非零活动 ID 的所有事件都是同一活动的一部分。
- 若要指示活动的开始,提供程序应将 opcode 设置为 WINEVENT_OPCODE_START 具有特定非零活动 ID 的第一个事件 (start 事件) 。 如果活动在逻辑上嵌套在另一个活动中,则提供程序应将 start 事件的相关活动 ID 字段设置为父活动的 ID。
- 若要指示活动的结束时间,提供程序应将 opcode 设置为 WINEVENT_OPCODE_STOP 最后一个具有特定非零活动 ID 的事件 (停止 事件) 。
要使活动 ID 有用,新生成的活动 ID 必须在本地唯一,即不能在跟踪中生成同一 ID 两次。
可以使用 EventActivityIdControl 创建活动 ID,该 ID 生成本地唯一的 ID,这些 ID 保证在本地系统上的所有进程中都是唯一的,直到系统重新启动为止。 还可以使用 GUID (全局唯一标识符) 作为活动 ID。 可以使用 UuidCreate 等 API 创建 GUID。
用户模式线程具有线程本地 128 位活动 ID 值 (线程的活动 ID) 。 线程活动 ID 初始化为 0 (即创建线程时 GUID_NULL) 。 可以使用 EventActivityIdControl 读取或更新线程活动 ID。 线程活动 ID 将用作 EventWrite 写入的所有事件以及 EventWriteTransfer 或 EventWriteEx 写入的所有事件的活动 ID,其中 ActivityId 参数为 NULL。
重要
更改线程的活动 ID 的函数在退出之前应小心还原原始活动 ID。 否则,函数对线程活动 ID 的更改将干扰调用函数的组件的活动。
使用显式指定的活动 ID
如果活动不限于单个线程,或者想要避免其他组件干扰覆盖线程的活动 ID,则可能需要通过 EventWriteTransfer 或 EventWriteEx 的 ActivityId 字段显式指定事件活动,而不是使用自动线程活动 ID。
如果使用 清单 和 消息编译器 写入事件,则生成的 MC.exe -um
宏使用线程的活动 ID,而生成的 MC.exe -km
宏支持活动 ID 参数。
最初, -um
宏仅在用户模式下工作,宏 -km
仅在内核模式下工作,因此用户模式代码只能使用当前线程的活动 ID。 但是,从 MC.exe 版本 10.0.17741 开始,生成的 MC.exe -km
宏可用于用户模式和内核模式,因此可以使用 MC.exe -km
生成接受活动 ID 参数的宏。
(MC 生成的代码不支持设置事件的相关活动 ID.)
如果使用 TraceLoggingProvider.h 编写事件, TraceLoggingWrite 宏将使用线程的活动 ID,而 TraceLoggingWriteActivity 接受活动 ID 和相关活动 ID 的参数。 或者,可以将 TraceLoggingActivity.h 中的 C++ 类用于 TraceLogging 活动。
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows Vista [桌面应用 | UWP 应用] |
最低受支持的服务器 | Windows Server 2008 [桌面应用 | UWP 应用] |
目标平台 | Windows |
标头 | evntprov.h |
Library | Advapi32.lib |
DLL | Advapi32.dll |