LogFileMode

The key to the many options for configuring a tracing session, known informally as a logger, is a set of bit flags that are typically experienced in user mode as the LogFileMode member of an EVENT_TRACE_PROPERTIES structure. Among the options is that a tracing session may have its buffers in user-mode memory, but if these are not specified, the tracing session is the kernel’s to start and manage. For communication to the kernel, nowadays through the NtTraceControl function, the session’s properties are repackaged as a WMI_LOGGER_INFORMATION structure, still with the bit flags as a ULONG member named LogFileMode. This also is how the kernel presents the properties to itself for those sessions that it starts from AutoLogger settings in the registry. This note is concerned solely with this kernel-mode interpretation of the LogFileMode in the WMI_LOGGER_INFORMATION and the eventual retention of this LogFileMode as the LoggerMode in the WMI_LOGGER_CONTEXT.

Most of the log file modes are documented by Microsoft as Logging Mode Constants and are defined as macros in EVNTRACE.H. Not all were documented immediately. For a few, Microsoft’s names are known only from the NTWMI.H header which Microsoft published in the Enterprise edition of the Windows Driver Kit (WDK) for Windows 10 version 1511.

In the following list of log file modes, the versions are those for which the flag is known to have some explicit recognition by the kernel, even if only to reject it as invalid. Where versions are not shown, the flag is not known to the kernel but may instead be vital to the separate NTDLL implementation that lets user-mode processes do their own event tracing.

Validation

Very many of the options are incompatible with other LogFileMode flags and in some cases with other WMI_LOGGER_INFORMATION members. By incompatible is here meant that the combination prevents the tracing session from starting: NtTraceControl fails, returning STATUS_INVALID_PARAMETER.

The table for each flag shows the constraints that apply if the flag is set when trying to start a tracing session. These constraints are what the programmer (or the user who configures AutoLogger settings) would need to know if thinking to use the flag. Note that many of these constraints were not enforced immediately that the flag was defined and many seem never to have been formally documented.

Less easily tabulated are the many requirements and inconsistencies that do not prevent a tracing session from starting but are instead corrected silently. When one flag requires another, the natural resolution of the other’s absence is to proceed as if the other had been set. The one is said (below) to imply the other. Where two flags are inconsistent, a resolution that stops short of treating them as incompatible is to accept one but proceed as if the other had been clear. The one is said to override the other. The terminology is in flux and perhaps never will be sorted out: if you don’t like it, please consider that Microsoft, who designed this as part of a product that makes money, is not known to have ever published any serious attempt.

EVENT_TRACE_FILE_MODE_SEQUENTIAL

In version 6.0 and higher, EVENT_TRACE_FILE_MODE_SEQUENTIAL is implied if either EVENT_TRACE_FILE_MODE_APPEND or EVENT_TRACE_FILE_MODE_NEWFILE is set.

EVENT_TRACE_FILE_MODE_CIRCULAR

Not only are EVENT_TRACE_FILE_MODE_SEQUENTIAL and EVENT_TRACE_FILE_MODE_CIRCULAR opposed in all versions, but the former is a sort of default. In version 6.0 and higher, to omit EVENT_TRACE_FILE_MODE_CIRCULAR is in effect to set EVENT_TRACE_FILE_MODE_SEQUENTIAL unless both EVENT_TRACE_FILE_MODE_APPEND and EVENT_TRACE_FILE_MODE_NEWFILE are also omitted.

Also starting with version 6.0, setting EVENT_TRACE_FILE_MODE_CIRCULAR is one way to allow EVENT_TRACE_NONSTOPPABLE_MODE for an AutoLogger session.

EVENT_TRACE_FILE_MODE_APPEND

EVENT_TRACE_FILE_MODE_NEWFILE

See that EVENT_TRACE_FILE_MODE_NEWFILE is not permitted for some particular tracing sessions. These are identified, originally, by the GUID that is specified in the Guid member of the Wnode or is inferred from the session’s name. The SystemTraceControlGuid and CKCLGuid identify respectively the NT Kernel Logger and the (essentially undocumented) Circular Kernel Context Logger. That it “should not be used for NT kernel logger sessions” has been documented since at least 2003 and generalises in version 6.2 to EVENT_TRACE_SYSTEM_LOGGER_MODE.

Not documented, but perhaps not a surprise, is that EVENT_TRACE_FILE_MODE_NEWFILE is not permitted for AutoLogger sessions. These are distinguished by the 0x00000002 bit in the Flags.

EVENT_TRACE_FILE_MODE_PREALLOCATE

EVENT_TRACE_NONSTOPPABLE_MODE

Microsoft included EVENT_TRACE_NONSTOPPABLE_MODE in its documentation of Logging Mode Constants some time between 2010 and 2012 as being “supported on Windows Vista and later.” As the documentation notes, it is intended for tracing sessions that the kernel starts from AutoLogger settings in the registry. Enforcement is through the undocumented Flags bit, which the documented StartTrace function does not set.

Even for AutoLogger sessions, EVENT_TRACE_NONSTOPPABLE_MODE requires one of:

• EVENT_TRACE_FILE_MODE_CIRCULAR;
• EVENT_TRACE_BUFFERING_MODE;
• EVENT_TRACE_REAL_TIME_MODE but without a LogFileName and, in version 6.0, without EVENT_TRACE_DELAY_OPEN_FILE_MODE.

EVENT_TRACE_SECURE_MODE

Nothing invalidates EVENT_TRACE_SECURE_MODE, but it is implied by EVENT_TRACE_BUFFER_INTERFACE_MODE in version 6.1 and higher.

EVENT_TRACE_REAL_TIME_MODE

Nothing invalidates EVENT_TRACE_REAL_TIME_MODE, but it is overridden by EVENT_TRACE_BUFFERING_MODE in version 6.1 and higher.

In all versions, i.e., 5.0 and higher, EVENT_TRACE_REAL_TIME_MODE is required if all the following are absent:

• EVENT_TRACE_DELAY_OPEN_FILE_MODE, in versions 5.0 to 6.0;
• EVENT_TRACE_BUFFERING_MODE, in version 6.0 and higher;
• LogFileHandle, in versions 5.0 to 5.2;
• LogFileName, in version 6.0 and higher.

In version 6.0 and higher, setting EVENT_TRACE_REAL_TIME_MODE without also providing a LogFileName or setting EVENT_TRACE_DELAY_OPEN_FILE_MODE allows EVENT_TRACE_NONSTOPPABLE_MODE for an AutoLogger session (see above).

EVENT_TRACE_DELAY_OPEN_FILE_MODE

The original ETW implementation allowed that a log file for a tracing session need not be opened until an event provider actually does write an event for the tracing session to record. This feature is discontinued for version 5.1 but EVENT_TRACE_DELAY_OPEN_FILE_MODE continues to be recognised in the kernel’s code, though without effect in version 6.1 and higher.

In versions 5.0 to 6.0, EVENT_TRACE_DELAY_OPEN_FILE_MODE is required if all the following are absent:

• EVENT_TRACE_REAL_TIME_MODE;
• EVENT_TRACE_BUFFERING_MODE, in version 6.0;
• LogFileHandle, in versions 5.0 to 5.2;
• LogFileName, in version 6.0.

EVENT_TRACE_BUFFERING_MODE

In version 6.0 and higher, EVENT_TRACE_BUFFERING_MODE is required if all the following are absent:

• EVENT_TRACE_REAL_TIME_MODE;
• EVENT_TRACE_DELAY_OPEN_FILE_MODE, in version 6.0 only;
• LogFileName.

Also starting with version 6.0, setting EVENT_TRACE_BUFFERING_MODE allows EVENT_TRACE_NONSTOPPABLE_MODE for an AutoLogger session.

EVENT_TRACE_USE_GLOBAL_SEQUENCE

EVENT_TRACE_USE_LOCAL_SEQUENCE

EVENT_TRACE_RELOG_MODE

Early documentation of EVENT_TRACE_RELOG_MODE was relatively expansive. Nowadays, documentation has it as “reserved for internal use”, and the whole technical content of what the option exists for is “Logs the event without including EVENT_TRACE_HEADER.” Once upon a time, Microsoft continued with

The logger was started to re-log one or more existing log files to a new log file. Therefore, the variable portion of the re-logged event already has a header from the old log file.

The option evidently does something useful, just not something that Microsoft wants programmers writing for themselves. But that’s another story. The option only ever has been meaningful for user-mode tracing sessions. It’s unknown to the kernel until version 6.2 makes a point of rejecting it explicitly.

EVENT_TRACE_BUFFER_INTERFACE_MODE

EVENT_TRACE_KD_FILTER_MODE

Nothing invalidates EVENT_TRACE_KD_FILTER_MODE. It is, however, overridden by EVENT_TRACE_BUFFERING_MODE in versions 6.1 to 6.2. In version 6.2, this override of EVENT_TRACE_KD_FILTER_MODE still overrides EVENT_TRACE_USE_PAGED_MEMORY.

EVENT_TRACE_STOP_ON_HYBRID_SHUTDOWN

EVENT_TRACE_PERSIST_ON_HYBRID_SHUTDOWN

EVENT_TRACE_USE_PAGED_MEMORY

A tracing session that has kernel-mode buffers uses non-paged memory by default but can specify EVENT_TRACE_USE_PAGED_MEMORY. The buffers are then reserved in paged memory, of course. This is not suitable for kernel-mode event providers, which are free to write events when access to paged memory is forbidden. This is in general not a problem if such providers never are enabled for the session, but to specify EVENT_TRACE_SYSTEM_LOGGER_MODE is to want from the start that the kernel is an event provider and is ruled out.

Specifying EVENT_TRACE_KD_FILTER_MODE also declares an intention to receive events when paged memory may be out of bounds, but the resolution (also in version 6.2 and higher) is just that EVENT_TRACE_USE_PAGED_MEMORY is overridden.

EVENT_TRACE_SYSTEM_LOGGER_MODE

EVENT_TRACE_COMPRESSED_MODE

Compression of buffers for writing to the log file dates from version 6.2 for tracing sessions that have user-mode buffers and are managed by NTDLL instead of the kernel. The compression functionality eventually gets some support for kernel-mode tracing sessions in the 1607 release of Windows 10. Until then, the kernel explicitly rejects EVENT_TRACE_COMPRESSED_MODE as invalid.