EventWriteEx 函数 (evntprov.h)

编写具有活动 ID、可选相关活动 ID、会话筛选器和特殊选项的 ETW 事件。

语法

ULONG EVNTAPI EventWriteEx(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG64                Filter,
  [in]           ULONG                  Flags,
  [in, optional] LPCGUID                ActivityId,
  [in, optional] LPCGUID                RelatedActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

参数

[in] RegHandle

提供程序的注册句柄。 句柄来自 EventRegister。 生成的事件将使用与句柄关联的 ProviderId。

[in] EventDescriptor

EVENT_DESCRIPTOR 包含事件信息 (元数据) ,包括 ID、版本、级别、关键字、通道、Opcode 和任务。

重要

ProviderId、Level 和 Keyword 是筛选事件的主要方法。 其他类型的筛选是可能的,但开销要高得多。 始终为每个事件分配非零级别和关键字。

[in] Filter

64 位掩码值。 每个设置位指示应从特定跟踪会话中排除此事件。

Filter 参数与基于 EnableCallback 中的 FilterData 执行自定义事件筛选的事件提供程序一起使用。

如果不支持自定义事件筛选器,或者事件是否应写入所有跟踪会话,请将 筛选器 设置为零。 否则,请将 Filter 设置为不应接收事件的会话的按位 OR。

[in] Flags

标志 设置为零,用于正常事件处理。

标志 设置为特殊事件处理 EVENT_WRITE_FLAG 值的组合。

  • EVENT_WRITE_FLAG_INPRIVATE (0x2)

    指示此事件应从已设置 EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE 选项的任何记录器中排除。

[in, optional] ActivityId

指向此事件的 128 位活动 ID 的可选指针。 如果这是非 NULL, EventWriteEx 将使用事件的活动 ID 的指定值。 如果为 NULL, EventWriteEx 将使用当前线程的活动 ID。

跟踪处理工具可以使用事件的活动 ID 将事件组织成称为活动的组。 有关活动 ID 的其他信息,请参阅 EventActivityIdControl

[in, optional] RelatedActivityId

指向 128 位活动 ID 的可选指针,该 ID 是此事件的活动的父级。 如果这是非 NULL, EventWriteEx 将为事件的相关活动 ID 使用指定的值。 如果为 NULL,则事件将没有相关的活动 ID。 通常,在活动的 START 事件上设置相关活动 ID, (使用 Opcode = START) 记录的活动的第一个事件。

跟踪处理工具可以使用事件的相关活动 ID 来确定活动之间的关系,例如,相关活动是新启动活动的父活动。 有关相关活动 ID 的其他信息,请参阅 EventActivityIdControl

[in] UserDataCount

UserData 中的EVENT_DATA_DESCRIPTOR结构数。 最大数字为 128。

[in, optional] UserData

UserDataCount 的数组EVENT_DATA_DESCRIPTOR结构,用于描述要包含在事件中的数据。 如果用户DataCount 为零,则 UserData 可能为 NULL

每个 EVENT_DATA_DESCRIPTOR 描述事件中包含的一个内存块。 将按没有填充或对齐方式连接指定的块以形成事件内容。 如果使用基于清单的解码,则事件内容必须与与清单中的事件关联的模板中指定的布局匹配。

返回值

如果成功或错误代码,则返回 ERROR_SUCCESS 。 可能的错误代码包括:

  • ERROR_INVALID_PARAMETER:一个或多个参数无效。
  • ERROR_INVALID_HANDLE:提供程序的注册句柄无效。
  • ERROR_ARITHMETIC_OVERFLOW:事件大小大于允许的最大 (64KB - 标头) 。
  • ERROR_MORE_DATA:会话缓冲区大小对于事件来说太小。
  • ERROR_NOT_ENOUGH_MEMORY:当填充的缓冲区尝试刷新到磁盘时发生,但磁盘 IO 的速度不够快。 当磁盘速度缓慢且事件流量过大时,就会发生这种情况。 最终,不再有空 (空) 缓冲区,并且事件被删除。
  • STATUS_LOG_FILE_FULL:实时播放文件已满。 在实时使用者使用播放文件中的事件之前,不会将事件记录到会话。

错误代码主要用于调试和诊断方案。 大多数生产代码应继续运行并继续报告事件,即使无法编写 ETW 事件,因此发布版本通常应忽略错误代码。

注解

大多数事件提供程序不会直接调用 EventWriteEx 。 相反,大多数事件提供程序都是使用 ETW 框架实现的,该框架包装对 EventRegisterEventWriteExEventUnregister 的调用。 例如,可以 编写事件清单 ,然后使用 消息编译器 为事件生成 C/C++ 代码,也可以使用 TraceLogging 来避免需要清单。

EventWriteEx 将根据 RegHandle) 、Level、Keyword 和其他事件特征确定的 ProviderId (将事件路由到相应的跟踪会话。 如果没有跟踪会话记录此事件,此函数将不执行任何操作并返回 ERROR_SUCCESS

若要降低任何跟踪会话未记录的事件的性能影响,可以调用 EventEnabled 来确定任何跟踪会话是否在准备数据和调用 EventWriteEx 之前记录事件。

提供程序可以定义会话用于基于事件数据筛选事件的筛选器。 核心筛选器基于级别和关键字。 事件提供程序可以支持更复杂的筛选器。 事件提供程序可以从 EnableCallbackFilterData 参数接收筛选器信息。 提供程序可以评估筛选器并使用 EventWriteExFilter 参数来指示某些跟踪会话未传递筛选器,因此不应接收事件。

要求

   
最低受支持的客户端 Windows 7 [桌面应用|UWP 应用]
最低受支持的服务器 Windows Server 2008 R2 [桌面应用|UWP 应用]
目标平台 Windows
标头 evntprov.h
Library Advapi32.lib
DLL Advapi32.dll

另请参阅

EventActivityIdControl

EventRegister

EventWrite

EventWriteTransfer

编写基于清单的事件