EVENT_TRACE_HEADER 结构 (evntrace.h)

  • 项目

EVENT_TRACE_HEADER 结构包含由 TraceEvent 编写的所有事件通用的标准事件跟踪信息。

语法

typedef struct _EVENT_TRACE_HEADER {
  USHORT        Size;
  union {
    USHORT FieldTypeFlags;
    struct {
      UCHAR HeaderType;
      UCHAR MarkerFlags;
    } DUMMYSTRUCTNAME;
  } DUMMYUNIONNAME;
  union {
    ULONG Version;
    struct {
      UCHAR  Type;
      UCHAR  Level;
      USHORT Version;
    } Class;
  } DUMMYUNIONNAME2;
  ULONG         ThreadId;
  ULONG         ProcessId;
  LARGE_INTEGER TimeStamp;
  union {
    GUID      Guid;
    ULONGLONG GuidPtr;
  } DUMMYUNIONNAME3;
  union {
    struct {
      ULONG KernelTime;
      ULONG UserTime;
    } DUMMYSTRUCTNAME;
    ULONG64 ProcessorTime;
    struct {
      ULONG ClientContext;
      ULONG Flags;
    } DUMMYSTRUCTNAME2;
  } DUMMYUNIONNAME4;
} EVENT_TRACE_HEADER, *PEVENT_TRACE_HEADER;

成员

Size

事件的字节总数。 大小 包括标头结构的大小，以及追加到标头的任何特定于事件的数据的大小。

输入时，大小必须小于事件跟踪会话缓冲区的大小减去 72 (0x48) 。

在输出中，请勿在计算中使用此数字。

DUMMYUNIONNAME

DUMMYUNIONNAME.FieldTypeFlags

保留。

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.HeaderType

保留。

DUMMYUNIONNAME.DUMMYSTRUCTNAME.MarkerFlags

保留。

DUMMYUNIONNAME2

DUMMYUNIONNAME2.Version

这是 类成员的汇总。 低序字节包含 Type，下一个字节包含 Level，最后两个字节包含版本。

DUMMYUNIONNAME2.Class

DUMMYUNIONNAME2.Class.Type

事件类型。 提供程序可以定义自己的事件类型，也可以使用下表中列出的预定义事件类型。

  • EVENT_TRACE_TYPE_CHECKPOINT：检查点事件。 用于不在活动开始或结束时的事件。

  • EVENT_TRACE_TYPE_DC_END：数据收集结束事件。

  • EVENT_TRACE_TYPE_DC_START：数据收集启动事件。

  • EVENT_TRACE_TYPE_DEQUEUE：取消排队事件。 在活动开始前排队时使用。 使用 EVENT_TRACE_TYPE_START 标记工作项排队的时间。 使用取消排队事件类型来标记项目实际开始工作的时间。 使用 EVENT_TRACE_TYPE_END 标记项目工作完成的时间。

  • EVENT_TRACE_TYPE_END：结束事件。 使用 跟踪多步骤事件的最终状态。

  • EVENT_TRACE_TYPE_EXTENSION：扩展事件。 用于作为上一个事件的延续的事件。 例如，当事件跟踪记录的数据超过会话缓冲区可容纳的数据数时，请使用扩展事件类型。

  • EVENT_TRACE_TYPE_INFO：信息事件。 这是默认事件类型。

  • EVENT_TRACE_TYPE_REPLY：回复事件。 请求资源的应用程序可以接收多个响应时使用。 例如，如果客户端应用程序请求 URL，而 Web 服务器通过发送多个文件进行答复，则收到的每个文件都可以标记为回复事件。

  • EVENT_TRACE_TYPE_START：启动事件。 使用 跟踪多步骤事件的初始状态。

如果定义自己的事件类型，则应使用从 10 开始的数字。 但是，没有什么可以阻止你使用任何你希望使用的数字。 如果事件跟踪类 GUID 支持多个事件类型，则使用者将使用 事件类型来确定事件以及如何解释其内容。

DUMMYUNIONNAME2.Class.Level

提供程序定义的值，用于定义用于生成事件的严重性级别。 该值的范围为 0 到 255。 控制器在调用 EnableTraceEx2 函数时指定严重性级别。 提供程序通过从其 ControlCallback 实现调用 GetTraceEnableLevel 函数来检索严重性级别。 提供程序使用 值来设置此成员。

ETW 定义了以下严重性级别。 选择高于 1 的级别还将包括较低级别的事件。 例如，如果控制器指定TRACE_LEVEL_WARNING (3) ，则提供程序还会生成TRACE_LEVEL_FATAL (1 个) ，TRACE_LEVEL_ERROR (2 个) 事件。

值 含义
TRACE_LEVEL_CRITICAL (1) 异常退出或终止事件
TRACE_LEVEL_ERROR (2) 严重错误事件
TRACE_LEVEL_WARNING (3) 警告事件，例如分配失败
TRACE_LEVEL_INFORMATION (4) 非错误事件，例如进入或退出事件
TRACE_LEVEL_VERBOSE (5) 详细的跟踪事件

DUMMYUNIONNAME2.Class.Version

指示用于记录事件的事件跟踪类的版本。 如果事件跟踪类只有一个版本，则指定零。 版本告知使用者使用哪个 MOF 类来破译事件数据。

ThreadId

在输出中，标识生成事件的线程。

请注意，在 Windows 2000 上， ThreadId 是 ULONGLONG 值。

ProcessId

在输出中，标识生成事件的进程。

Windows 2000： 不支持此成员。

TimeStamp

在输出中，包含事件发生的时间。 解析是系统时间，除非 EVENT_TRACE_LOGFILE 的 ProcessTraceMode 成员包含 PROCESS_TRACE_MODE_RAW_TIMESTAMP 标志，在这种情况下，解析取决于控制器创建会话时EVENT_TRACE_PROPERTIES的 Wnode.ClientContext 成员的值。

DUMMYUNIONNAME3

DUMMYUNIONNAME3.Guid

事件跟踪类 GUID。 可以使用类 GUID 标识事件类别，使用 Class.Type 成员标识事件类别中的事件。

或者，可以使用 GuidPtr 成员来指定类 GUID。

Windows XP 和 Windows 2000： 类 GUID 必须以前使用 RegisterTraceGuids 函数进行注册。

DUMMYUNIONNAME3.GuidPtr

指向事件跟踪类 GUID 的指针。 或者，可以使用 Guid 成员指定类 GUID。

写入事件时，ETW 使用指针将 GUID 复制到事件， (该 GUID 包含在事件中，而不是指针) 。

如果使用此成员， 则 Flags 成员还必须包含WNODE_FLAG_USE_GUID_PTR。

DUMMYUNIONNAME4

DUMMYUNIONNAME4.DUMMYSTRUCTNAME

DUMMYUNIONNAME4.DUMMYSTRUCTNAME.KernelTime

内核模式指令的已用执行时间（以 CPU 时间单位为单位）。 如果使用专用会话，请改用 ProcessorTime 成员中的 值。 有关详细信息，请参阅“备注”。

DUMMYUNIONNAME4.DUMMYSTRUCTNAME.UserTime

用户模式指令的已用执行时间（以 CPU 时间单位为单位）。 如果使用专用会话，请改用 ProcessorTime 成员中的 值。 有关详细信息，请参阅“备注”。

DUMMYUNIONNAME4.ProcessorTime

对于专用会话，用户模式指令的已用执行时间（以 CPU 刻度为单位）。

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2.ClientContext

保留。

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2.Flags

必须将此成员设置为 WNODE_FLAG_TRACED_GUID，并且可以根据需要指定以下任意组合。

  • WNODE_FLAG_USE_GUID_PTR：指定 GuidPtr 成员是否包含类 GUID。

  • WNODE_FLAG_USE_MOF_PTR：指定 MOF_FIELD 结构的数组是否包含追加到此结构的事件数据。 数组中的元素数限制为 MAX_MOF_FIELDS。

注解

在设置任何成员之前，请确保将此结构的内存初始化为零。

可以使用 KernelTime 和 UserTime 成员来确定一组指令的 CPU 成本（以单位为单位） (值指示在记录) 时向该线程收取的 CPU 使用率。 例如，如果事件 A 和事件 B 由同一线程连续记录，并且它们的 CPU 使用率为 150 和 175，则该线程在事件 A 和 B 之间执行的活动花费 25 个 CPU 时间单位 (175 – 150) 。

TRACE_LOGFILE_HEADER 结构的 TimerResolution 包含 CPU 使用率计时器的分辨率（以 100 纳秒为单位）。 可以使用具有内核时间和用户时间值的计时器分辨率来确定指令集使用的 CPU 时间量。 例如，如果计时器分辨率为 156,250，则 25 个 CPU 时间单位为 0.39 秒， (156,250 * 25 * 100 / 1,000,000,000) 。 这是事件 A 和 B 之间的指令集使用的 CPU 时间 (未经过的时钟时间) 量。

但请注意，CPU 使用率计时器分辨率通常非常低， () 大约 10 毫秒或更多。 因此，CPU 使用率数字不能用于计算高准确度线程之间的 CPU 时间使用情况。 相反，它们适用于长期统计类型的分析。

要求

要求 值
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
标头 evntrace.h

另请参阅

EVENT_TRACE

EventCallback

TraceEvent