EVENT_DESCRIPTOR 结构 (evntprov.h)

项目
02/26/2024

EVENT_DESCRIPTOR 结构包含有关 ETW 事件的信息 (元数据) 。

语法

typedef struct _EVENT_DESCRIPTOR {
  USHORT    Id;
  UCHAR     Version;
  UCHAR     Channel;
  UCHAR     Level;
  UCHAR     Opcode;
  USHORT    Task;
  ULONGLONG Keyword;
} EVENT_DESCRIPTOR, *PEVENT_DESCRIPTOR;

成员

Id

用于标识基于清单的事件的 16 位数字。

对于基于清单的 ETW，Provider.DecodeGuid + Event.Id + Event.Version 组合应唯一标识一个事件，即具有相同 DecodeGuid、ID 和 Version 的所有事件应具有相同的字段集，字段名称、字段类型或字段顺序均无变化。

对于无清单 ETW (即 TraceLogging) ，Id 字段通常没有意义，通常设置为 0。 TraceLogging 事件通常由事件名称（而不是事件 ID）标识。

Version

一个 8 位数字，用于指定基于清单的事件的版本。

版本指示对具有特定 ID 的事件定义的修订。具有给定 ID 的所有事件都应具有类似的语义，但版本更改可用于指示对事件详细信息的次要修改，例如更改字段的类型或添加新字段。

Channel

用于启用特殊事件处理的 8 位数字。

基于清单的事件通常使用通道 0。
基于 TraceLogging 的事件通常使用通道 11。
具有提供程序特征的基于清单的事件通常使用通道 12。
其他通道值可以与事件日志事件一起使用。

低于 16 的通道值保留供 Microsoft 使用，以便 ETW 运行时启用特殊处理。 ETW 运行时将忽略通道值 16 及更高版本， (视为与通道 0) 相同，并且可以提供用户定义的语义。

Level

用于描述事件的严重性或重要性的 8 位数字。

重要

事件级别是筛选事件的主要方法。始终为每个事件分配有意义的 (非零) 级别。

级别值 0 到 5 由 Microsoft (查看 evntrace.h 和 winmeta.h) 定义。保留级别值 6 到 15。级别值 16 到 255 可由事件提供程序定义。

值	语义
LOG_ALWAYS (0)	事件绕过基于级别的事件筛选。事件不应使用此级别。
关键 (1)	严重错误
错误 (2)	错误
警告 (3)	警告
INFO (4)	信息
详细 (5)	详细

事件集合会话可以设置级别筛选器，这意味着会话将仅接受其中 eventDescriptor.Level <= session.LevelFilter的事件。请注意，级别为 0 的事件将绕过基于级别的筛选。

Opcode

用于标记具有特殊语义的事件的 8 位数字。跟踪解码器可以使用此值来组织和关联事件。全局识别的操作码值在 winmeta.h 中定义。大多数事件使用 INFO (0) 。可以为操作码值 10 到 239 提供用户定义的语义。

操作码 START (1) 和 STOP (2) 用于指示 ETW 活动的开始和结束，如下所示：

生成跟踪中唯一的活动 ID，通常使用 EventActivityIdControl。
如果有任何) ，请编写操作码 = START、活动 ID = 生成的活动 ID 和相关活动 ID = 父活动 ID (开始事件。
使用 opcode = INFO、活动 ID = 生成的活动 ID 编写任意数量的活动信息事件。
使用 opcode = STOP，活动 ID = 生成的活动 ID 编写停止事件。

然后，跟踪解码工具可以根据其活动 ID 将这些事件组织成组。

Task

用于批注事件或相关事件组的 16 位数字。

事件任务代码可用于提供程序定义的任何目的。任务代码 0 是默认值，用于指示没有向事件分配任何特殊任务代码。 ETW 清单支持将本地化字符串分配给每个任务代码。任务代码可用于将事件分组为类别，或仅将本地化的“任务”字符串与每个事件相关联。

Keyword

一个 64 位位掩码，用于指示事件在一组事件类别中的成员身份。

重要

事件关键字 (keyword) 是筛选事件的主要方法。始终为每个事件分配有意义的 (非零) 关键字 (keyword) 。

关键字 (keyword) (位掩码0xFFFF000000000000) 的前 16 位由 Microsoft 定义。关键字 (keyword) (位掩码0x0000FFFFFFFFFFFF) 的低 48 位由事件提供程序定义。例如，事件提供程序可以将位 0 (位掩码0x1) 定义为“I/O”类别，将位 1 位 (位掩码0x2) 定义为“UI”类别，将位 2 (位掩码0x4) 定义为“性能度量”类别。在这种情况下，事件关键字 (keyword) 可能设置为0x5，指示事件同时处于“I/O”和“性能度量”类别中。

事件集合会话可以设置 MatchAnyKeyword 和 MatchAllKeyword 筛选器，这意味着会话将仅接受以下表达式为 true 的事件：

eventDescriptor.Keyword == 0 || (
    (eventDescriptor.Keyword & session.MatchAnyKeyword) != 0 &&
    (eventDescriptor.Keyword & session.MatchAllKeyword) == session.MatchAllKeyword
)

请注意，关键字 (keyword) 为 0 的事件通常会绕过基于关键字 (keyword) 筛选。

提示

从Windows 10版本 1507 及更高版本开始，事件收集会话可以排除其关键字 (keyword) 设置为 0 的事件。为此，请在EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0配置提供程序时传递给 EnableTraceEx2 的 ENABLE_TRACE_PARAMETERS 结构的字段中包含标志EnableProperty。

注解

调用 EventWrite 写入事件时使用此结构。还可以在调用 EventEnabled 时使用它来确定是否应 (生成事件，即确定是否有任何事件侦听器对事件) 感兴趣。

注意

大多数事件提供程序不会直接使用 EVENT_DESCRIPTOR 。相反，大多数事件提供程序都是使用 ETW 框架实现的，该框架包装对 EventRegister、 EventWriteEx 和 EventUnregister 的调用。例如，可以编写事件清单，然后使用消息编译器为事件生成 C/C++ 代码，或者使用 TraceLogging 来避免需要清单。有关此结构的成员如何与检测清单相关的详细信息，请参阅 EventDefinitionType 复杂类型的属性。

此结构包含在 EVENT_HEADER 结构中，当您使用带有 EventRecordCallback 回调的 ProcessTrace 使用事件时，该结构随事件记录一起返回。

注意

处理基于 MOF 的事件时，事件标识包含在 Opcode 字段中，而不是 Id 字段中。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
标头	evntprov.h (包括 Evntprov.h)