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

另请参阅

EventWriteTransfer