Formatting the Properties Parameter
The Properties parameter of the StartKernelTrace function points to an EVENT_TRACE_PROPERTIES structure. This structure specifies the configuration of certain aspects of session behavior.
You must follow these guidelines when formatting the contents of this structure:
You must format the first member of the EVENT_TRACE_PROPERTIES structure as a WNODE_HEADER structure. In the following discussion, this member is referred as Wnode.
You must set the following EVENT_TRACE_PROPERTIES.Wnode members in order to configure kernel trace control:
This member contains the total size of memory allocated, in bytes, of the event tracing session properties. The size of memory must include enough space to store:
- The EVENT_TRACE_PROPERTIES structure.
- The session name string.
- The log file name string.
Each tracing session must have a GUID defined to reference the session.
For an NT Kernel Logger session, this member must be set to SystemTraceControlGuid. For more information about SystemTraceControlGuid, see NT Kernel Logger Constants.
This member sets the clock resolution that is used when the logging time stamp for each event is calculated. The default value for this member is Query performance counter (1).
You can specify one of the following values:
Query performance counter (QPC).
The QPC provides a high-resolution (100 nanoseconds) time stamp which is comparatively more expensive to retrieve.
You should use this resolution if you have high event rates, or if the consumer merges events from different buffers.
Note that on older computers, the time stamp may not be accurate because the counter sometimes skips forward due to hardware errors.
The system time provides a low-resolution (10 milliseconds) time stamp which is comparatively less expensive to retrieve.
Note that if the volume of events is high, the resolution for system time may not be fine enough to determine the sequence of events. In this case, a set of events will have the same time stamp, but the order in which Event Tracing for Windows (ETW) delivers the events may not be correct.
CPU cycle counter.
The CPU counter provides the highest resolution time stamp and is the least expensive to retrieve. However, the CPU counter is unreliable and should not be used in production. For example, on some computers, the timers will change frequency due to thermal and power changes, in addition to stopping in some states.
If your hardware does not support this clock type, ETW uses system time.
In Windows Server 2003, Windows XP SP1, and Windows XP, this value is not supported. It was introduced in Windows Server 2003 SP1 and Windows XP SP2.
This member must contain WNODE_FLAG_TRACED_GUID to indicate that the structure contains event tracing information and the information is sent to a logger. WNODE_FLAG_TRACED_GUID is defined in Evntrace.h.
Other EVENT_TRACE_PROPERTIES members that you should set include the following:
Indicates which logging modes are to be used in the kernel event tracing session. You can use this member to specify that events are to be written to a log file, a real-time consumer, or both.
This member can also be used to specify that the session is a private logger session. One or more modes can be specified. For a list of possible modes, see LoggingModeConstants.
Note Do not specify real-time logging unless there are real-time consumers ready to consume the events. If there are no real-time consumers the events are written to a playback file. The size of the playback file is limited. If the limit is reached, no new events are logged to the log file or the playback file. The logging functions fail with STATUS_LOG_FILE_FULL.
The EnableFlags member is used only for NT Kernel Logger sessions. EnableFlags identifies to the kernel logger which events to trace. By using logical OR, this member can contain one or more values. In addition to the events specified, the kernel logger also logs hardware configuration events.
With the introduction of the Kernel Tracing Control API, the following trace control flags are added:
Starting with the Microsoft Windows SDK for Windows Server 2008 and .NET Framework 3.5, these new flags are available in the Evntrace.h file included in the SDK.
For more information on these new flags, see New Trace Control Flags. Event trace flags that exist are explained at EVENT_TRACE_PROPERTIES.
This number represents the offset from the start of the structure's allocated memory to beginning of the null-terminated string that contains the log file name.
Consider the following list when you name and allocate the log file:
It is recommended that the file name should use an .etl extension.
All folders in the path must exist.
The path can be relative, absolute, local, or remote.
The path must not contain environment variables as they are not expanded.
The user who initiates the trace must have write permission for 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 logger's sessions, and the sequential number that is added to log files created using the new file log mode.
Also, consider the following when you work with log file configurations:
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 zero. If you specify only real-time logging and also provide an offset with a valid log file name, WPT/ETW uses the log file name to create a sequential log file and log events to the log file. WPT/ETW also creates the sequential log file if LogFileMode is zero 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.
This member represents the offset from the start of the structure's allocated memory to beginning of the null-terminated string that contains the session name.
Consider the following list when naming logger sessions:
The session name is limited to 1,024 characters.
The session name is case-insensitive and must be unique.
When allocating memory for this structure, sufficient memory must be reserved to include the session name and log file name following the structure.
The session name must come before the log file name in memory. The log file name must be copied into the offset area. The StartKernelTrace function writes the session name defined by KERNEL_LOGGER_NAME.
As per the type of log file chosen, it may be necessary to set the MaximumFileSize member. For more details on how to set the fields of EVENT_TRACE_PROPERTIES, see EVENT_TRACE_PROPERTIES Structure..
Note It is not necessary to set the logger name at the LoggerNameOffset as StartKernelTrace will always use the KERNEL_LOGGER_NAME value to call StartKernelTrace. The StartKernelTrace API checks if the Wnode.Guid corresponds to SystemTraceControlGuid and returns ERROR_INVALID_PARAMETER if it does not. If Wnode.Guid corresponds to KernelRundownGuid, the logger name should be specified. The KernelRundownGuid is the control GUID used to log events such as existing process information, thread information, images loaded per process, and hardware configuration like CPU, Video, Disk, Network cards, Services, Power, PNP, and Disk IDE Channels.
Build date: 5/5/2012