EVENT_TRACE_HEADER structure (evntrace.h)

The EVENT_TRACE_HEADER structure contains standard event tracing information common to all events written by TraceEvent.

Syntax

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;

Members

Size

Total number of bytes of the event. Size includes the size of the header structure, plus the size of any event-specific data appended to the header.

On input, the size must be less than the size of the event tracing session's buffer minus 72 (0x48).

On output, do not use this number in calculations.

DUMMYUNIONNAME

DUMMYUNIONNAME.FieldTypeFlags

Reserved.

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.HeaderType

Reserved.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.MarkerFlags

Reserved.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.Version

This is a roll-up of the members of Class. The low-order byte contains the Type, the next byte contains the Level, and the last two bytes contain the version.

DUMMYUNIONNAME2.Class

DUMMYUNIONNAME2.Class.Type

Type of event. A provider can define their own event types or use the predefined event types listed in the following table.

  • EVENT_TRACE_TYPE_CHECKPOINT: Checkpoint event. Use for an event that is not at the start or end of an activity.

  • EVENT_TRACE_TYPE_DC_END: Data collection end event.

  • EVENT_TRACE_TYPE_DC_START: Data collection start event.

  • EVENT_TRACE_TYPE_DEQUEUE: Dequeue event. Use when an activity is queued before it begins. Use EVENT_TRACE_TYPE_START to mark the time when a work item is queued. Use the dequeue event type to mark the time when work on the item actually begins. Use EVENT_TRACE_TYPE_END to mark the time when work on the item completes.

  • EVENT_TRACE_TYPE_END: End event. Use to trace the final state of a multi-step event.

  • EVENT_TRACE_TYPE_EXTENSION: Extension event. Use for an event that is a continuation of a previous event. For example, use the extension event type when an event trace records more data than can fit in a session buffer.

  • EVENT_TRACE_TYPE_INFO: Informational event. This is the default event type.

  • EVENT_TRACE_TYPE_REPLY: Reply event. Use when an application that requests resources can receive multiple responses. For example, if a client application requests a URL, and the web server replies by sending several files, each file received can be marked as a reply event.

  • EVENT_TRACE_TYPE_START: Start event. Use to trace the initial state of a multi-step event.

If you define your own event types, you should use numbers starting from 10. However, there is nothing to prevent you from using any numbers that you wish to use. If your event trace class GUID supports multiple event types, consumers will use the event type to determine the event and how to interpret its contents.

DUMMYUNIONNAME2.Class.Level

Provider-defined value that defines the severity level used to generate the event. The value ranges from 0 to 255. The controller specifies the severity level when it calls the EnableTraceEx2 function. The provider retrieves the severity level by calling the GetTraceEnableLevel function from its ControlCallback implementation. The provider uses the value to set this member.

ETW defines the following severity levels. Selecting a level higher than 1 will also include events for lower levels. For example, if the controller specifies TRACE_LEVEL_WARNING (3), the provider also generates TRACE_LEVEL_FATAL (1) and TRACE_LEVEL_ERROR (2) events.

Value Meaning
TRACE_LEVEL_CRITICAL (1) Abnormal exit or termination events
TRACE_LEVEL_ERROR (2) Severe error events
TRACE_LEVEL_WARNING (3) Warning events such as allocation failures
TRACE_LEVEL_INFORMATION (4) Non-error events such as entry or exit events
TRACE_LEVEL_VERBOSE (5) Detailed trace events

DUMMYUNIONNAME2.Class.Version

Indicates the version of the event trace class that you are using to log the event. Specify zero if there is only one version of your event trace class. The version tells the consumer which MOF class to use to decipher the event data.

ThreadId

On output, identifies the thread that generated the event.

Note that on Windows 2000, ThreadId was a ULONGLONG value.

ProcessId

On output, identifies the process that generated the event.

Windows 2000: This member is not supported.

TimeStamp

On output, contains the time that the event occurred. The resolution is system time unless the ProcessTraceMode member of EVENT_TRACE_LOGFILE contains the PROCESS_TRACE_MODE_RAW_TIMESTAMP flag, in which case the resolution depends on the value of the Wnode.ClientContext member of EVENT_TRACE_PROPERTIES at the time the controller created the session.

DUMMYUNIONNAME3

DUMMYUNIONNAME3.Guid

Event trace class GUID. You can use the class GUID to identify a category of events and the Class.Type member to identify an event within the category of events.

Alternatively, you can use the GuidPtr member to specify the class GUID.

Windows XP and Windows 2000: The class GUID must have been registered previously using the RegisterTraceGuids function.

DUMMYUNIONNAME3.GuidPtr

Pointer to an event trace class GUID. Alternatively, you can use the Guid member to specify the class GUID.

When the event is written, ETW uses the pointer to copy the GUID to the event (the GUID is included in the event, not the pointer).

If you use this member, the Flags member must also contain WNODE_FLAG_USE_GUID_PTR.

DUMMYUNIONNAME4

DUMMYUNIONNAME4.DUMMYSTRUCTNAME

DUMMYUNIONNAME4.DUMMYSTRUCTNAME.KernelTime

Elapsed execution time for kernel-mode instructions, in CPU time units. If you are using a private session, use the value in the ProcessorTime member instead. For more information, see Remarks.

DUMMYUNIONNAME4.DUMMYSTRUCTNAME.UserTime

Elapsed execution time for user-mode instructions, in CPU time units. If you are using a private session, use the value in the ProcessorTime member instead. For more information, see Remarks.

DUMMYUNIONNAME4.ProcessorTime

For private sessions, the elapsed execution time for user-mode instructions, in CPU ticks.

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2.ClientContext

Reserved.

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2.Flags

You must set this member to WNODE_FLAG_TRACED_GUID, and may optionally specify any combination of the following.

  • WNODE_FLAG_USE_GUID_PTR: Specify if the GuidPtr member contains the class GUID.

  • WNODE_FLAG_USE_MOF_PTR: Specify if an array of MOF_FIELD structures contains the event data appended to this structure. The number of elements in the array is limited to MAX_MOF_FIELDS.

Remarks

Be sure to initialize the memory for this structure to zero before setting any members.

You can use the KernelTime and UserTime members to determine the CPU cost in units for a set of instructions (the values indicate the CPU usage charged to that thread at the time of logging). For example, if Event A and Event B are consecutively logged by the same thread and they have CPU usage numbers 150 and 175, then the activity that was performed by that thread between events A and B cost 25 CPU time units (175 – 150).

The TimerResolution of the TRACE_LOGFILE_HEADER structure contains the resolution of the CPU usage timer in 100-nanosecond units. You can use the timer resolution with the kernel time and user time values to determine the amount of CPU time that the set of instructions used. For example, if the timer resolution is 156,250, then 25 CPU time units is 0.39 seconds (156,250 * 25 * 100 / 1,000,000,000). This is the amount of CPU time (not elapsed wall clock time) used by the set of instructions between events A and B.

Note, however, that the CPU usage timer resolution is typically very low (around 10 or more milliseconds). Therefore, CPU usage numbers cannot be used to account for CPU time usage among threads with high accuracy. Rather, they are suitable for long term, statistical type of analysis.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Header evntrace.h

See also

EVENT_TRACE

EventCallback

TraceEvent