EVENT_TRACE_PROPERTIES

The EVENT_TRACE_PROPERTIES structure describes a tracing session, also known as an event logger, for the ControlTrace, FlushTrace, QueryAllTraces, QueryTrace, StartTrace, StopTrace and UpdateTrace functions. These are all documented functions and the structure too is documented.

A tracing session is a set of buffers that receive events from possibly many event providers and a mechanism for asynchronously flushing the buffers somewhere, typically but not necessarily to an Event Trace Log (ETL) file. The selection of event providers and the control of which events to receive from them is managed through other functions. These functions and this structure are concerned more with the configuration of the buffers and the mechanism of delivering the buffered events. There are many options. Their description starts with the EVENT_TRACE_PROPERTIES structure.

The EVENT_TRACE_PROPERTIES structure is a fixed-size header whose members describe many of the session’s properties directly, but it is typically followed by variable-size properties. The most notable such extensions of the header are the names of the tracing session itself and of the log file, if any, that events are written to. Indeed, from Microsoft’s documentation and from headers in the Software Development Kit (SDK) these are all there would seem to be, even now in 2020, but there are others and have been for nearly two decades since Windows XP.

The structure can be both input and output for these functions. When starting a tracing session, most members of the structure are meaningful on input to specify what the started session should do. For all the functions, many members are meaningful on output to report what the session does. This is important and useful: that a session is successfully started or updated does not certainly mean that all the desired properties expressed on input were accepted.

Layout

The EVENT_TRACE_PROPERTIES structure is 0x78 in both 32-bit and 64-bit Windows, but not from being the same in both:

WNODE_HEADER Wnode;

ULONG BufferSize;

ULONG MinimumBuffers;

ULONG MaximumBuffers;

ULONG MaximumFileSize;

ULONG LogFileMode;

ULONG FlushTimer;

ULONG EnableFlags;

LONG AgeLimit;

union {
    LONG AgeLimit;
    LONG FlushThreshold;
};

ULONG NumberOfBuffers;

ULONG FreeBuffers;

ULONG EventsLost;

ULONG BuffersWritten;

ULONG LogBuffersLost;

ULONG RealTimeBuffersLost;

HANDLE LoggerThreadId;

ULONG LogFileNameOffset;

ULONG LoggerNameOffset;

As noted above, the structure is intended as a fixed-size header for variable-size data. The BufferSize in the Wnode is the total size in bytes. This is required on input to all the applicable functions.

The WNODE_HEADER has many uses other than to start an EVENT_TRACE_PROPERTIES. Most of the Wnode is not meaningful for input to or output from the applicable functions, though some is used internally

File Size

The MaximumFileSize member is (roughly) the largest size to which the log file is permitted to grow, or is zero. The size is measured in MB typically, but in KB if EVENT_TRACE_USE_KBYTES_FOR_SIZE is set in the LogFileMode (see below). The StartTrace function requires a non-zero MaximumFileSize if any of the following bits are set in the LogFileMode:

• EVENT_TRACE_FILE_MODE_CIRCULAR
• EVENT_TRACE_FILE_MODE_NEWFILE
• EVENT_TRACE_FILE_MODE_PREALLOCATE
• EVENT_TRACE_USE_KBYTES_FOR_SIZE

Log File Mode

The LogFileMode member is interpreted in bit flags. Many are invalid if combined with others:

Enable Flags

The EnableFlags member has the following defined values:

However, a set EVENT_TRACE_FLAG_EXTENSION bit indicates that the 4-byte EnableFlags member is instead interpreted as a structure:

Log File Name

The LogFileNameOffset member is an offset in bytes from the start of the structure to the name of the log file as a null-terminated string, or is zero to denote that there is no name. This member is meaningful on input to the StartTrace function. Since the name is expected to lie in space after the structure but within the buffer, a valid non-zero LogFileNameOffset must be at least 0x78 and less than Wnode.BufferSize.

Logger Name

The LoggerNameOffset member is an offset in bytes from the start of the structure to the name of the logger as a null-terminated string, or is zero to denote that there is no name. This member is meaningful on input to the StartTrace function. Since the name is expected to lie in space after the structure but within the buffer, a valid non-zero LoggerNameOffset must be at least 0x78 and less than Wnode.BufferSize.