- 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 additional 200MB of disk space whether or not you are using the maximum file size parameter. Therefore, if you specified 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
Time to wait before flushing buffers, in seconds. If zero, ETW flushes buffers as soon as they become full. If non-zero, 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 non-zero 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 non-zero value if the event rate is low to force events to be delivered before the buffer is full.
- 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.
| Flag | Meaning |
|---|
- EVENT_TRACE_FLAG_ALPC (0x00100000)
| Enables the ALPC event types.
|
- EVENT_TRACE_FLAG_CSWITCH (0x00000010)
| Enables the following Thread event type:
|
- 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:
|
- EVENT_TRACE_FLAG_DISPATCHER (0x00000800)
| Enables the following Thread event type:
|
- EVENT_TRACE_FLAG_DPC (0x00000020)
| Enables the following PerfInfo event type:
|
- EVENT_TRACE_FLAG_DRIVER (0x00800000)
| Enables the following DiskIo event types:
|
- EVENT_TRACE_FLAG_FILE_IO (0x02000000)
| Enables the following FileIo event types:
|
- EVENT_TRACE_FLAG_FILE_IO_INIT (0x04000000)
| Enables the following FileIo event type:
|
- EVENT_TRACE_FLAG_IMAGE_LOAD (0x00000004)
| Enables the following Image event type:
|
- EVENT_TRACE_FLAG_INTERRUPT (0x00000040)
| Enables the following PerfInfo event type:
|
- 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_PROCESS (0x00000001)
| Enables the following Process event type:
|
- EVENT_TRACE_FLAG_PROCESS_COUNTERS (0x00000008)
| Enables the following Process_V2 event type:
|
- EVENT_TRACE_FLAG_PROFILE (0x01000000)
| Enables the following PerfInfo event type:
|
- EVENT_TRACE_FLAG_REGISTRY (0x00020000)
| Enables the Registry event types.
|
- EVENT_TRACE_FLAG_SPLIT_IO (0x00200000)
| Enables the SplitIo event types.
|
- EVENT_TRACE_FLAG_SYSTEMCALL (0x00000080)
| Enables the following PerfInfo event type:
|
- EVENT_TRACE_FLAG_THREAD (0x00000002)
| Enables the following Thread event type:
|
- EVENT_TRACE_FLAG_VIRTUAL_ALLOC (0x00004000)
| Enables the following PageFault_V2 event type:
|
- 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.
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.
Typically, you should not set these values and instead let ETW determine the size and number of buffers.