This page is being prepared for a substantial reworking. Some content may be temporarily missing. Temporarily may turn into indefinitely. New content may be more than usually defective. The page is now published only as a revision in progress. Use with caution.

EVENT_HEADER

The EVENT_HEADER (formally _EVENT_HEADER) is one of several types of fixed-size header that introduce variable-size data for events that are logged through Event Tracing for Windows (ETW). As with other types of event, those that begin with an EVENT_HEADER accumulate first in trace buffers. To have these events persist in this raw form for ready inspection, configure the event tracing session to flush the trace buffers to an Event Trace Log (ETL) file.

Among the various trace headers, the EVENT_HEADER is unusual in that it is not just a transitory implementation detail for how one type of event gets packed into the trace buffers or even for how NTDLL passes events to the kernel. It is also the header, within an EVENT_RECORD, when event data is unpacked for event consumers—even of event data that had a different header while in the trace buffers. This article is concerned only with the packed form.

Availability

The EVENT_HEADER was introduced for Windows Vista.

Usage

Two ways are known that an event begins with an EVENT_HEADER rather than some other trace header. One is that it is delivered to the kernel through the NtTraceEvent function. For this, the Flags argument masked with ETW_NT_TRACE_TYPE_MASK must be ETW_NT_FLAGS_TRACE_EVENT. The Fields argument must then address an event

Documentation Status

Presumably because of its role in interfaces that support event consumers, the EVENT_HEADER structure is defined in the EVNTCONS.H header for user-mode programming and is documented.

Note, however, that the EVENT_HEADER is documented merely as “defines information about the event” as if the structure exists solely for delivering the event to an event consumer. One might easily miss that the structure has a very much longer role in the life of most events, including even when NTDLL prepares an event for sending to the kernel.

Layout

The EVENT_HEADER is 0x50 bytes in both 32-bit and 64-bit Windows in all versions that are known to have it.

USHORT Size;

USHORT HeaderType;

USHORT Flags;

USHORT EventProperty;

ULONG ThreadId;

ULONG ProcessId;

LARGE_INTEGER TimeStamp;

GUID ProviderId;

EVENT_DESCRIPTOR EventDescriptor;

union {
    struct {
        ULONG KernelTime;
        ULONG UserTime;
    };
    ULONG64 ProcessorTime;
};

GUID ActivityId;

Size

The Size is the total, in bytes, of the EVENT_HEADER and all the event data that follows. To understand the fixed-size header, it helps to know that the variable-size data that follows it is broadly in two parts:

• extended data items added by the kernel, possibly from provider-supplied arguments;
• arbitrary event data, necessarily from the event provider.

Header Type

What distinguishes the EVENT_HEADER from other trace headers are special values in the bytes at offset 0x02 and 0x03. For the EVENT_HEADER, but for no other types of trace header, Microsoft models these bytes together as a 16-bit HeaderType. Whether they’re defined as two bytes or one word, two combinations of these bytes at offsets 0x02 and 0x03 distinguish that a trace header is specifically an EVENT_HEADER. Microsoft’s names for them as values for the HeaderType are known from an NTETW.H which Microsoft distributed with the original and Version 1511 editions of the Windows Driver Kit (WDK) for Windows 10:

Flags

Microsoft defines the following in EVNTCONS.H as bits for the Flags:

Microsoft defines them because they are set for the structure that is presented to event consumers. The Flags are mostly not meaningful (and cannot be set) in an EVENT_HEADER that is in the trace buffers. Some exist precisely to tell the event consumer that the event originated differently. For instance, an event that gets EVENT_HEADER_FLAG_TRACE_MESSAGE set in its presentation to an event consumer actually started its life with a MESSAGE_TRACE_HEADER.

Microsoft defines the following for EventProperty:

Most of the other members are generated at logging-time. The ProviderGuid and ActivityId are saved from function arguments.

Extended Data Items

The kernel sets EVENT_HEADER_FLAG_EXTENDED_INFO in the Flags to indicate that the EVENT_HEADER is followed by at least one extended data item. Each such item appears, after 8-byte alignment, as a fixed-size header and variable-size data. The header is an EVENT_HEADER_EXTENDED_DATA_ITEM, not quite as defined in EVNTCONS.H:

USHORT Reserved1;

USHORT ExtType;

struct {
    USHORT Linkage : 1;
    USHORT Reserved2 : 15;
};

USHORT DataSize;

ULONGLONG DataPtr;

The key difference is that DataPtr is not space for a 32-bit or 64-bit pointer to wherever the unpacking has placed the variable-size data. Instead, it holds that data, or at least the beginning of that data. The Reserved1 member is the total size, i.e., of the first 8 bytes of the EVENT_HEADER_EXTENDED_DATA_ITEM plus the DataSize bytes of variable-size data. The form of that data depends on the ExtType. Microsoft’s EVNTCONS.H defines the following values and names:

TO BE CONTINUED