EVENT_TRACE_PROPERTIES structure (evntrace.h)

The EVENT_TRACE_PROPERTIES structure contains information about an event tracing session. You use this structure with APIs such as StartTrace and ControlTrace when defining, updating, or querying the properties of a session.

Note

This is a version-1 structure. Additional options are supported by EVENT_TRACE_PROPERTIES_V2 (e.g. FilterDesc and V2Options).

Syntax

typedef struct _EVENT_TRACE_PROPERTIES {
  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;
} EVENT_TRACE_PROPERTIES, *PEVENT_TRACE_PROPERTIES;

Members

Wnode

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

BufferSize

Kilobytes of memory allocated for each event tracing session buffer. The minimum buffer size is 4 (4KB). The maximum buffer size is 16384 (16MB). Most trace sessions should use a buffer size of 64KB or less to avoid wasting memory and disk space. Prior to Windows 8: The maximum buffer size is 1024 (1MB).

Smaller buffer sizes reduce session memory usage and can help reduce log file size. Larger buffer sizes support collection of larger events because ETW does not fragment events across buffer boundaries and therefore cannot collect events larger than the buffer size. In scenarios involving extremely high data throughput, larger buffer sizes can also reduce CPU overhead.

• A session with small events and a low event rate (a few KB/s) should use a small buffer size (4KB to 16KB).
• A session with small events and a moderate event rate should use a medium buffer size (16KB to 32KB).
• A session with large events or a high event rate (a few MB/s) should use a large buffer size (64KB to 128KB).
• In rare cases when a large amount of memory should be reserved for a diagnostic trace with hundreds of megabytes of data per second, a huge buffer size (256KB to 1024KB) can reduce CPU overhead.

Note

Regardless of buffer size, ETW cannot collect events larger than 64KB.

ETW may adjust the requested BufferSize upwards in certain scenarios. For example, when writing a trace file to a disk, ETW may increase the buffer size to a multiple of the disk's physical block size.

Important

BufferSize is one of the most important parameters for a trace session. Large buffers usually waste memory and disk space. Trace sessions with large buffers (256KB or larger) should be used only for diagnostic investigations or testing, not for production tracing.

Tip

Do not use BufferSize to control the trace session's memory usage. Instead, select the buffer size based on your session's event size and event rate, then use the MinimumBuffers and MaximumBuffers parameters to adjust session memory usage.

MinimumBuffers

Minimum number of buffers reserved for the tracing session's buffer pool.

ETW may adjust this value in certain scenarios.

• If the logging mode includes the EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING flag, ETW will reserve at least 2 buffers.
• If the logging mode does not include the EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING flag, ETW will reserve at least 2 buffers for each logical processor.
• If this value is larger than an ETW-determined limit, ETW may reduce it to the limit to avoid excessive memory usage.

For file-mode and real-time traces with moderate event rates, most users should minimize memory usage by setting MinimumBuffers to 0 or to a small minimum (e.g. 4 or 8), allowing ETW to adjust the value upwards based on the number of processors. ETW will reserve the (adjusted) minimum number of buffers when the trace is started. If the buffers are filled more quickly than they can be processed, ETW will try to allocate addition buffers, up to the number specified by MaximumBuffers.

For buffering-mode (circular in-memory) traces, users should set the MinimumBuffers parameter according to the total amount of memory that you want ETW to reserve for the session. This is usually calculated based on the expected event rate and the amount of time you want the trace to cover. For example, if you expect a data rate of 16KB per second and you want your trace to record at least 60 seconds of data, you would need 960KB. Assuming a buffer size of 32KB, you would set MinimumBuffers to 30 (960KB total / 32KB per buffer = 30 buffers). ETW will reserve the (adjusted) minimum number of buffers when the trace is started. When all buffers are filled, ETW will reuse the oldest filled buffer for new events. Note that ETW will not allocate additional buffers (ETW ignores MaximumBuffers for buffering-mode traces).

MaximumBuffers

Maximum number of buffers to be allocated for the tracing session's buffer pool.

ETW may adjust this value in certain scenarios.

• If this value is less than the adjusted value of MinimumBuffers, ETW may increase it to a suitable value equal to or larger than MinimumBuffers.
• If this value is larger than an ETW-determined limit, ETW may reduce it to the limit.

Most users should start tuning their session by setting MinimumBuffers and MaximumBuffers to the same value. You might then increase the value of MaximumBuffers if the trace drops events during event rate peaks.

ETW cannot allocate on-demand buffers if the event is generated by a driver running at high IRQL. If your trace session needs to record events from high-IRQL kernel-mode providers, it may need to use a higher value of MinimumBuffers to force the buffers to be preallocated.

Note

ETW ignores MaximumBuffers for buffering-mode sessions (sessions that include logging mode EVENT_TRACE_BUFFERING_MODE). Buffering-mode sessions always allocate MinimumBuffers at the start of the trace collection and never allocate additional buffers.

MaximumFileSize

Maximum size of the file used to log events, in megabytes, or zero for no size limit. 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 set to a nonzero value 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 flags for the event tracing session. You use this member to specify whether you want events written to an in-memory circular buffer, a log file, or a real-time consumer. You can also use this member to specify other session characteristics, e.g. that the session is a private logger session. For a list of possible flags, see Logging Mode Constants.

ETW buffers events for real-time sessions when there are no real-time consumers for the session. Note that this buffering is limited. If the limit is reached, new events will be ignored and the logging functions fail with STATUS_LOG_FILE_FULL. Prior to Windows Vista: If there is no real-time consumer, events are discarded and logging continues.

Do not start a real-time logging session unless a real-time consumer will consume the events. A real-time session with no consumers will waste system resources (CPU, memory, and disk space for buffering the events).

If a consumer begins processing real-time events, the buffered events are consumed first. After all buffered events are consumed, the session will begin reporting new events.

FlushTimer

How often, in seconds, any non-empty trace buffers are flushed. The minimum flush time is 1 second.

• For file-mode sessions: Setting FlushTimer to 0 will disable time-based flushes (flush will occur when the buffer is filled, when the session is stopped, or when the session is explicitly flushed). Most file-mode traces should set FlushTimer to 0 to avoid wasted space in the trace file (i.e. so that disk space is not wasted storing mostly-empty buffers). You might want to set the timer to a non-zero value if there is a chance the trace might not be closed (e.g. if you want to be sure to get events even if the system crashes).
• For real-time sessions: Setting FlushTimer to 0 will enable a default timeout of 1 second. Real-time sessions should set the flush timer based on how quickly the data needs to be received. Note that a higher timer value will reduce CPU overhead for the trace. Most real-time traces should start with a timer of 5 or 10 seconds and tune the timer based on need.
• For buffered (circular in-memory) sessions, FlushTimer is not used. The trace data will only be flushed on-demand (i.e. flushed to a file via ControlTrace).

EnableFlags

A system logger session may set EnableFlags to indicate which SystemTraceProvider events should be included in the trace.

Note

EnableFlags is only valid for system loggers, i.e. trace sessions that are started using the EVENT_TRACE_SYSTEM_LOGGER_MODE logger mode flag, the KERNEL_LOGGER_NAME session name, the SystemTraceControlGuid session GUID, or the GlobalLoggerGuid session GUID.

This member can contain one or more of the following values. In addition to the events you specify, unless you specify EVENT_TRACE_FLAG_NO_SYSCONFIG, the logger also records hardware configuration events on Windows XP and system configuration events on Windows Server 2003 or later.

• 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:

  • CSwitch

  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):

  • FileIo_Name

• EVENT_TRACE_FLAG_DISK_IO (0x00000100)

  Enables the following DiskIo event types:

  • DiskIo_TypeGroup1
  • DiskIo_TypeGroup3

• EVENT_TRACE_FLAG_DISK_IO_INIT (0x00000400)

  Enables the following DiskIo event type:

  • DiskIo_TypeGroup2

  This value is supported on Windows Vista and later.

• EVENT_TRACE_FLAG_DISPATCHER (0x00000800)

  Enables the following Thread event type:

  • ReadyThread

  This value is supported on Windows 7, Windows Server 2008 R2, and later.

• EVENT_TRACE_FLAG_DPC (0x00000020)

  Enables the following PerfInfo event type:

  • DPC

  This value is supported on Windows Vista and later.

• EVENT_TRACE_FLAG_DRIVER (0x00800000)

  Enables the following DiskIo event types:

  • DriverCompleteRequest
  • DriverCompleteRequestReturn
  • DriverCompletionRoutine
  • DriverMajorFunctionCall
  • DriverMajorFunctionReturn

  This value is supported on Windows Vista and later.

• EVENT_TRACE_FLAG_FILE_IO (0x02000000)

  Enables the following FileIo event types:

  • FileIo_OpEnd

  This value is supported on Windows Vista and later.

• EVENT_TRACE_FLAG_FILE_IO_INIT (0x04000000)

  Enables the following FileIo event type:

  • FileIo_Create
  • FileIo_DirEnum
  • FileIo_Info
  • FileIo_ReadWrite
  • FileIo_SimpleOp

  This value is supported on Windows Vista and later.

• EVENT_TRACE_FLAG_IMAGE_LOAD (0x00000004)

  Enables the following Image event type:

  • Image_Load

• EVENT_TRACE_FLAG_INTERRUPT (0x00000040)

  Enables the following PerfInfo event type:

  • ISR

  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:

  • PageFault_HardFault

• EVENT_TRACE_FLAG_MEMORY_PAGE_FAULTS (0x00001000)

  Enables the following PageFault_V2 event type:

  • PageFault_TypeGroup1

• 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:

  • Process_TypeGroup1

• EVENT_TRACE_FLAG_PROCESS_COUNTERS (0x00000008)

  Enables the following Process_V2 event type:

  • Process_V2_TypeGroup2

  This value is supported on Windows Vista and later.

• EVENT_TRACE_FLAG_PROFILE (0x01000000)

  Enables the following PerfInfo event type:

  • SampledProfile

  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:

  • SysCallEnter
  • SysCallExit

  This value is supported on Windows Vista and later.

• EVENT_TRACE_FLAG_THREAD (0x00000002)

  Enables the following Thread event type:

  • Thread_TypeGroup1

• 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:

  • PageFault_VirtualAlloc

  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 (in bytes) from the start of this structure's allocated memory to beginning of the nul-terminated string that contains the log file name.

The file name normally has an .etl extension. All folders in the path must already exist (ETW will not create folders for you). The path can be relative, absolute, local, or remote. Environment variables in the path will not be 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 reserve enough memory to include the process identifier that will be 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, if 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 in addition to sending the events to real-time consumers. 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 reserve 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. See remarks for an example.

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 (in bytes) from the start of the structure's allocated memory to the beginning of the nul-terminated string that contains the session name.

Important

Use a descriptive name for your session so that the session's ownership and usage can be determined from the session name. Do not use a GUID or other non-descriptive value. Do not append random digits to make your session name unique. ETW sessions are a limited resource so your component should not be starting multiple sessions. If your component's session is already running when your component starts, your component should clean up the orphaned session rather than creating a second session.

The session name is limited to 1,024 characters. The session name is case-insensitive. The system will not start a new session if another session with the same name is already running.

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

Remarks

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.

Be sure to initialize the memory for this structure to zero before setting any members. For example:

typedef struct EventTracePropertyData {
    EVENT_TRACE_PROPERTIES Props;
    WCHAR LoggerName[128];
    WCHAR LogFileName[1024];
} EventTracePropertyData;

EventTracePropertyData data = {0};
data.Props.Wnode.BufferSize = sizeof(data);
data.Props.Wnode.Flags = WNODE_FLAG_TRACED_GUID;
data.Props.LogFileNameOffset = offsetof(EventTracePropertyData, LogFileName);
data.Props.LoggerNameOffset = offsetof(EventTracePropertyData, LoggerName);

Events from providers are written to a session's buffers. When a buffer in a file or real-time session is full (or when the FlushTimer expires), the session flushes the buffer either by writing the events to a log file, delivering them to a real-time consumer, or both. If a session's buffers are filled faster than they can be flushed, new buffers are allocated and added to the session's buffer pool, up to MaximumBuffers. Beyond this limit, the session discards incoming events until a buffer becomes available. Each session keeps a record of the number of events discarded (see the EventsLost member).

To view session statistics, such as EventsLost while the session is running, call the ControlTrace function and set the ControlCode parameter to EVENT_TRACE_CONTROL_QUERY.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps | UWP apps]
Minimum supported server	Windows 2000 Server [desktop apps | UWP apps]
Header	evntrace.h

See also

StartTrace

ControlTrace

QueryAllTraces

Logging Mode Constants

EVENT_TRACE_PROPERTIES_V2

WNODE_HEADER