Export (0) Print
Expand All
8 out of 13 rated this helpful - Rate this topic

EVENT_TRACE_PROPERTIES structure

The EVENT_TRACE_PROPERTIES 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.

Syntax


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

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.

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

Used only for NT Kernel Logger sessions. Tells the kernel logger which events to trace. 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.

FlagMeaning
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_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.

Remarks

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

Events from providers are written to a session's buffers. When a buffer is full, the session flushes the buffer either by writing the events to a log file, delivering them to a real-time consumer, or both. If the 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 the maximum number specified. 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).

ETW does not free unused buffers.

Windows 2000:  ETW frees unused buffers based on the AgeLimit member value.

You use the BufferSize, MinimumBuffers, and MaximumBuffers members to configure the buffers for an event tracing session when you define the session or anytime during the tracing session. ETW uses the physical memory and number of processors available on the computer to determine if the values are reasonable. If ETW determines the values are not reasonable, ETW will determine the correct size and overwrite the values.

Typically, you should not set these values and instead let ETW determine the size and number of buffers.

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

Minimum supported client

Windows 2000 Professional [desktop apps | Windows Store apps]

Minimum supported server

Windows 2000 Server [desktop apps | Windows Store apps]

Header

Evntrace.h

See also

ControlTrace
QueryAllTraces
WNODE_HEADER

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.