EventWriteEx 函数 (evntprov.h)

项目
02/26/2024

写入具有活动 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、版本、级别、关键字、通道、操作码和任务。

重要

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

[in] Filter

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

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

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

[in] Flags

将标志设置为零，以便正常处理事件。

将 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 的可选指针。如果这是非 NULL， 则 EventWriteEx 将为事件的相关活动 ID 使用指定的值。如果为 NULL，则事件将没有相关的活动 ID。相关活动 ID 通常在活动的 START 事件 (活动的第一个事件上设置，记录为 Opcode = START) 。

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

[in] UserDataCount

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

[in, optional] UserData

UserDataCount的数组EVENT_DATA_DESCRIPTOR描述事件中要包含的数据的结构。如果 UserDataCount 为零，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 框架实现的，该框架包装对 EventRegister、 EventWriteEx 和 EventUnregister 的调用。例如，可以编写事件清单，然后使用消息编译器为事件生成 C/C++ 代码，或者使用 TraceLogging 来避免需要清单。

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

若要降低未由任何跟踪会话记录的事件的性能影响，可以调用 EventEnabled 以确定是否有任何跟踪会话正在记录事件，然后再准备数据和调用 EventWriteEx。

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

要求

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

另请参阅

EventActivityIdControl

通过

EventWriteEx 函数 (evntprov.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源