EVENT_TRACE_PROPERTIES_V2 structure

The EVENT_TRACE_PROPERTIES_V2 structure contains information about an event tracing session. You use this structure when you define a session, change the properties of a session, or query for the properties of a session. This is extended from the EVENT_TRACE_PROPERTIES structure.

Syntax

typedef struct EVENT_TRACE_PROPERTIES_V2 {
  WNODE_HEADER             Wnode;
  ULONG                    BufferSize;
  ULONG                    MinimumBuffers;
  ULONG                    MaximumBuffers;
  ULONG                    MaximumFileSize;
  ULONG                    LogFileMode;
  ULONG                    FlushTimer;
  ULONG                    EnableFlags;
  LONG                     AgeLimit;
  ULONG                    NumberOfBuffers;
  ULONG                    FreeBuffers;
  ULONG                    EventsLost;
  ULONG                    BuffersWritten;
  ULONG                    LogBuffersLost;
  ULONG                    RealTimeBuffersLost;
  HANDLE                   LoggerThreadId;
  ULONG                    LogFileNameOffset;
  ULONG                    LoggerNameOffset;
  ULONG                    VersionNumber;
  PEVENT_FILTER_DESCRIPTOR FilterDesc;
  ULONG                    FilterDescCount;
  union {
    struct {
      ULONG Wow : 1;
      ULONG QpcDeltaTracking : 1;
    }
    ULONG V2Options;
  };
} EVENT_TRACE_PROPERTIES_V2, *PEVENT_TRACE_PROPERTIES_V2;

Members

Wnode

A WNODE_HEADER structure. You must specify the BufferSize, Flags, and Guid members, and optionally the ClientContext member.

BufferSize

Amount of memory allocated for each event tracing session buffer, in kilobytes. The maximum buffer size is 1 MB. ETW uses the size of physical memory to calculate this value. For more information, see Remarks.

If an application expects a relatively low event rate, the buffer size should be set to the memory page size. If the event rate is expected to be relatively high, the application should specify a larger buffer size, and should increase the maximum number of buffers.

The buffer size affects the rate at which buffers fill and must be flushed. Although a small buffer size requires less memory, it increases the rate at which buffers must be flushed.

MinimumBuffers

Minimum number of buffers allocated for the event tracing session's buffer pool. The minimum number of buffers that you can specify is two buffers per processor. For example, on a single processor computer, the minimum number of buffers is two. Note that if you use the EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING logging mode, the number of processors is assumed to be 1.

MaximumBuffers

Maximum number of buffers allocated for the event tracing session's buffer pool. Typically, this value is the minimum number of buffers plus twenty. ETW uses the buffer size and the size of physical memory to calculate this value. This value must be greater than or equal to the value for MinimumBuffers. Note that you do not need to set this value if LogFileMode contains EVENT_TRACE_BUFFERING_MODE; instead, the total memory buffer size is instead the product of MinimumBuffers and BufferSize.

MaximumFileSize

Maximum size of the file used to log events, in megabytes. Typically, you use this member to limit the size of a circular log file when you set LogFileMode to EVENT_TRACE_FILE_MODE_CIRCULAR. This member must be specified if LogFileMode contains EVENT_TRACE_FILE_MODE_PREALLOCATE, EVENT_TRACE_FILE_MODE_CIRCULAR or EVENT_TRACE_FILE_MODE_NEWFILE

If you are using the system drive (the drive that contains the operating system) for logging, ETW checks for an additional 200MB of disk space, regardless of whether you are using the maximum file size parameter. Therefore, if you specify 100MB as the maximum file size for the trace file in the system drive, you need to have 300MB of free space on the drive.

LogFileMode

Logging modes for the event tracing session. You use this member to specify that you want events written to a log file, a real-time consumer, or both. You can also use this member to specify that the session is a private logger session. You can specify one or more modes. For a list of possible modes, see Logging Mode Constants.

Do not specify real-time logging unless there are real-time consumers ready to consume the events. If there are no real-time consumers, ETW writes the events to a playback file. However, the size of the playback file is limited. If the limit is reached, no new events are logged (to the log file or playback file) and the logging functions fail with STATUS_LOG_FILE_FULL.

Prior to Windows Vista: If there was no real-time consumer, the events were discarded and logging continues.

If a consumer begins processing real-time events, the events in the playback file are consumed first. After all events in the playback file are consumed, the session will begin logging new events.

FlushTimer

How often, in seconds, the trace buffers are forcibly flushed. The minimum flush time is 1 second. This forced flush is in addition to the automatic flush that occurs whenever a buffer is full and when the trace session stops.

If zero, ETW flushes buffers as soon as they become full. If nonzero, ETW flushes all buffers that contain events based on the timer value. Typically, you want to flush buffers only when they become full. Forcing the buffers to flush (either by setting this member to a nonzero value or by calling FlushTrace) can increase the file size of the log file with unfilled buffer space.

If the consumer is consuming events in real time, you may want to set this member to a nonzero value if the event rate is low to force events to be delivered before the buffer is full.

For the case of a realtime logger, a value of zero (the default value) means that the flush time will be set to 1 second. A realtime logger is when LogFileMode is set to EVENT_TRACE_REAL_TIME_MODE.

EnableFlags

A system logger must set EnableFlags to indicate which SystemTraceProvider events should be included in the trace. This is also used for NT Kernel Logger sessions. This member can contain one or more of the following values. In addition to the events you specify, the kernel logger also logs hardware configuration events on Windows XP or system configuration events on Windows Server 2003.

Flag Meaning
EVENT_TRACE_FLAG_ALPC
0x00100000
Enables the ALPC event types.
This value is supported on Windows Vista and later.
EVENT_TRACE_FLAG_CSWITCH
0x00000010
Enables the following Thread event type:
This value is supported on Windows Vista and later.
EVENT_TRACE_FLAG_DBGPRINT
0x00040000
Enables the DbgPrint and DbgPrintEx calls to be converted to ETW events.
EVENT_TRACE_FLAG_DISK_FILE_IO
0x00000200
Enables the following FileIo event type (you must also enable EVENT_TRACE_FLAG_DISK_IO):
EVENT_TRACE_FLAG_DISK_IO
0x00000100
Enables the following DiskIo event types:
EVENT_TRACE_FLAG_DISK_IO_INIT
0x00000400
Enables the following DiskIo event type:
This value is supported on Windows Vista and later.
EVENT_TRACE_FLAG_DISPATCHER
0x00000800
Enables the following Thread event type:
This value is supported on Windows 7, Windows Server 2008 R2, and later.
EVENT_TRACE_FLAG_DPC
0x00000020
Enables the following PerfInfo event type:
This value is supported on Windows Vista and later.
EVENT_TRACE_FLAG_DRIVER
0x00800000
Enables the following DiskIo event types:
This value is supported on Windows Vista and later.
EVENT_TRACE_FLAG_FILE_IO
0x02000000
Enables the following FileIo event types:
This value is supported on Windows Vista and later.
EVENT_TRACE_FLAG_FILE_IO_INIT
0x04000000
Enables the following FileIo event type:
This value is supported on Windows Vista and later.
EVENT_TRACE_FLAG_IMAGE_LOAD
0x00000004
Enables the following Image event type:
EVENT_TRACE_FLAG_INTERRUPT
0x00000040
Enables the following PerfInfo event type:
This value is supported on Windows Vista and later.
EVENT_TRACE_FLAG_JOB
0x00080000
This value is supported on Windows 10
EVENT_TRACE_FLAG_MEMORY_HARD_FAULTS
0x00002000
Enables the following PageFault_V2 event type:
EVENT_TRACE_FLAG_MEMORY_PAGE_FAULTS
0x00001000
Enables the following PageFault_V2 event type:
EVENT_TRACE_FLAG_NETWORK_TCPIP
0x00010000
Enables the TcpIp and UdpIp event types.
EVENT_TRACE_FLAG_NO_SYSCONFIG
0x10000000
Do not do a system configuration rundown.
This value is supported on Windows 8, Windows Server 2012, and later.
EVENT_TRACE_FLAG_PROCESS
0x00000001
Enables the following Process event type:
EVENT_TRACE_FLAG_PROCESS_COUNTERS
0x00000008
Enables the following Process_V2 event type:
This value is supported on Windows Vista and later.
EVENT_TRACE_FLAG_PROFILE
0x01000000
Enables the following PerfInfo event type:
This value is supported on Windows Vista and later.
EVENT_TRACE_FLAG_REGISTRY
0x00020000
Enables the Registry event types.
EVENT_TRACE_FLAG_SPLIT_IO
0x00200000
Enables the SplitIo event types.
This value is supported on Windows Vista and later.
EVENT_TRACE_FLAG_SYSTEMCALL
0x00000080
Enables the following PerfInfo event type:
This value is supported on Windows Vista and later.
EVENT_TRACE_FLAG_THREAD
0x00000002
Enables the following Thread event type:
EVENT_TRACE_FLAG_VAMAP
0x00008000
Enables the map and unmap (excluding image files) event type.
This value is supported on Windows 8, Windows Server 2012, and later.
EVENT_TRACE_FLAG_VIRTUAL_ALLOC
0x00004000
Enables the following PageFault_V2 event type:
This value is supported on Windows 7, Windows Server 2008 R2, and later.

 

AgeLimit

Not used.

Windows 2000: Time delay before unused buffers are freed, in minutes. The default is 15 minutes.

NumberOfBuffers

On output, the number of buffers allocated for the event tracing session's buffer pool.

FreeBuffers

On output, the number of buffers that are allocated but unused in the event tracing session's buffer pool.

EventsLost

On output, the number of events that were not recorded.

BuffersWritten

On output, the number of buffers written.

LogBuffersLost

On output, the number of buffers that could not be written to the log file.

RealTimeBuffersLost

On output, the number of buffers that could not be delivered in real-time to the consumer.

LoggerThreadId

On output, the thread identifier for the event tracing session.

LogFileNameOffset

Offset from the start of the structure's allocated memory to beginning of the null-terminated string that contains the log file name.

The file name should use the .etl extension. All folders in the path must exist. The path can be relative, absolute, local, or remote. The path cannot contain environment variables (they are not expanded). The user must have permission to write to the folder.

The log file name is limited to 1,024 characters. If you set LogFileMode to EVENT_TRACE_PRIVATE_LOGGER_MODE or EVENT_TRACE_FILE_MODE_NEWFILE, be sure to allocate enough memory to include the process identifier that is appended to the file name for private loggers sessions, and the sequential number that is added to log files created using the new file log mode.

If you do not want to log events to a log file (for example, you specify EVENT_TRACE_REAL_TIME_MODE only), set LogFileNameOffset to 0. If you specify only real-time logging and also provide an offset with a valid log file name, ETW will use the log file name to create a sequential log file and log events to the log file. ETW also creates the sequential log file if LogFileMode is 0 and you provide an offset with a valid log file name.

If you want to log events to a log file, you must allocate enough memory for this structure to include the log file name and session name following the structure. The log file name must follow the session name in memory.

Trace files are created using the default security descriptor, meaning that the log file will have the same ACL as the parent directory. If you want access to the files restricted, create a parent directory with the appropriate ACLs.

LoggerNameOffset

Offset from the start of the structure's allocated memory to beginning of the null-terminated string that contains the session name.

The session name is limited to 1,024 characters. The session name is case-insensitive and must be unique.

Windows 2000: Session names are case-sensitive. As a result, duplicate session names are allowed. However, to reduce confusion, you should make sure your session names are unique.

When you allocate the memory for this structure, you must allocate enough memory to include the session name and log file name following the structure. The session name must come before the log file name in memory. You must copy the log file name to the offset but you do not copy the session name to the offset—the StartTrace function copies the name for you.

VersionNumber

The version of the structure. This should be set to "2" for this version.

FilterDesc

Supported EVENT_FILTER_DESCRIPTOR filter types for system wide private loggers: EVENT_FILTER_TYPE_EXECUTABLE_NAME and EVENT_FILTER_TYPE_PID

A pointer to an array of EVENT_FILTER_DESCRIPTOR structures that points to the filter data. The number of elements in the array is specified in the FilterDescCount member. There can only be one filter for a specific filter type as specified by the Type member of the EVENT_FILTER_DESCRIPTOR structure.

This is only applicable to Private Loggers. The only time this should not be null is when it is used for system wide Private Loggers.

FilterDescCount

The number of filters that the FilterDesc points to. The only time this should not be zero is for system wide Private Loggers.

V2Options

An extended set of configuration options:

Wow: Marks whether or not this logger was created by a Wow64 process. This should never be set on input as it is reserved for internal use.

QpcDeltaTracking: When set, this turns on QPC Delta Tracking events for use in Container scenarios. When a Container's QPC clock is not synchronized with the QPC clock of its host, this feature will insert QPC Delta events into the trace to allow the parsing engine to correlate a Container's trace with traces from the host. This is supported beginning in the next major release of Windows 10.

Remarks

This structure behaves similarly to EVENT_TRACE_PROPERTIES with a few exceptions.

The beginning of the structure is defined exactly as EVENT_TRACE_PROPERTIES to allow this new structure to be compatible with systems running versions of Windows before Windows 10, version 1703 and will be treated as EVENT_TRACE_PROPERTIES.

When using this structure, be sure to include WNODE_FLAG_VERSIONED_PROPERTIES in Wnode.Flags to indicate that this is the version two structure.

Note that the filters passed into ControlTrace, QueryTrace, StartTrace, and StopTrace by this structure are the same format as filters consumed by the EnableTraceEx2 function.

Requirements

Minimum supported client
Windows 10 [desktop apps only]
Minimum supported server
Windows Server 2016 [desktop apps only]
Header
Evntrace.h

See also

EVENT_TRACE_PROPERTIES

WNODE_HEADER