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;
  union {
    LONG AgeLimit;
    LONG FlushThreshold;
  } DUMMYUNIONNAME;
  ULONG                    NumberOfBuffers;
  ULONG                    FreeBuffers;
  ULONG                    EventsLost;
  ULONG                    BuffersWritten;
  ULONG                    LogBuffersLost;
  ULONG                    RealTimeBuffersLost;
  HANDLE                   LoggerThreadId;
  ULONG                    LogFileNameOffset;
  ULONG                    LoggerNameOffset;
  union {
    struct {
      ULONG VersionNumber : 8;
    } DUMMYSTRUCTNAME;
    ULONG V2Control;
  } DUMMYUNIONNAME2;
  ULONG                    FilterDescCount;
  PEVENT_FILTER_DESCRIPTOR FilterDesc;
  union {
    struct {
      ULONG Wow : 1;
      ULONG QpcDeltaTracking : 1;
    } DUMMYSTRUCTNAME;
    ULONG64 V2Options;
  } DUMMYUNIONNAME3;
} 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 <b>MinimumBuffers</b>. Note that  you do not need to set this value if <b>LogFileMode</b> contains <b>EVENT_TRACE_BUFFERING_MODE</b>; instead, the total memory buffer size is instead the product of  <b>MinimumBuffers</b> and <b>BufferSize</b>.
    
    
        `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 <b>LogFileMode</b> to <b>EVENT_TRACE_FILE_MODE_CIRCULAR</b>. This member must be specified if <b>LogFileMode</b> contains <b>EVENT_TRACE_FILE_MODE_PREALLOCATE</b>, <b>EVENT_TRACE_FILE_MODE_CIRCULAR</b> or <b>EVENT_TRACE_FILE_MODE_NEWFILE</b>

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 <b>EnableFlags</b> 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.

`DUMMYUNIONNAME`
        `DUMMYUNIONNAME.AgeLimit`

        Not used.

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

        `DUMMYUNIONNAME.FlushThreshold`

        
    
    
        `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.

        `DUMMYUNIONNAME2`

        
    
    
        `DUMMYUNIONNAME2.DUMMYSTRUCTNAME`

        
    
    
        `DUMMYUNIONNAME2.DUMMYSTRUCTNAME.VersionNumber`

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

        
    
    
        `FilterDescCount`

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

        Supported <a href="https://docs.microsoft.com/windows/desktop/api/evntprov/ns-evntprov-event_filter_descriptor">EVENT_FILTER_DESCRIPTOR</a> filter types for system wide private loggers: <b>EVENT_FILTER_TYPE_EXECUTABLE_NAME</b> and <b>EVENT_FILTER_TYPE_PID</b>

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.

        `DUMMYUNIONNAME3`

        
    
    
        `DUMMYUNIONNAME3.DUMMYSTRUCTNAME`

        
    
    
        `DUMMYUNIONNAME3.DUMMYSTRUCTNAME.Wow`

        
    
    
        `DUMMYUNIONNAME3.DUMMYSTRUCTNAME.QpcDeltaTracking`

        
    
    
        `DUMMYUNIONNAME3.V2Options`

        
    

## Remarks
    This structure behaves similarly to <a href="https://docs.microsoft.com/windows/desktop/ETW/event-trace-properties">EVENT_TRACE_PROPERTIES</a> 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

    <a href="https://docs.microsoft.com/windows/desktop/ETW/event-trace-properties">EVENT_TRACE_PROPERTIES</a>

WNODE_HEADER