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 写入的所有事件以及 EventWriteTransferEventWriteEx 写入的所有事件的活动 ID,其中 ActivityId 参数为 NULL

重要

更改线程的活动 ID 的函数在退出之前应小心还原原始活动 ID。 否则,函数对线程活动 ID 的更改将干扰调用函数的组件的活动。

使用显式指定的活动 ID

如果活动不限于单个线程,或者想要避免其他组件干扰覆盖线程的活动 ID,则可能需要通过 EventWriteTransferEventWriteExActivityId 字段显式指定事件活动,而不是使用自动线程活动 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

另请参阅

EventWriteTransfer