Configuring and Starting an AutoLogger Session
The AutoLogger event tracing session records events that occur early in the operating system boot process. Applications and device drivers can use the AutoLogger session to capture traces before the user logs in. Note that some device drivers, such as disk device drivers, are not loaded at the time the AutoLogger session begins.
The AutoLogger differs from the Global Logger in the following ways:
- You can specify one or more AutoLogger sessions (the Global Logger was a single session to which everyone logged events).
- The AutoLogger sends an enable notification to the providers when the session starts (the Global Logger did not send an enable notification to the providers, so the providers had to rely on other means to know if the Global Logger session was started in order to begin logging events).
- The AutoLogger does not support logging NT Kernel Logger events (see the EnableFlags member of EVENT_TRACE_PROPERTIES). To log NT Kernel Logger events, you must use the Global Logger.
For more information on the Global Logger seesion, see Configuring and Starting the Global Logger Session.
Note
ETW supports the AutoLogger on Windows Vista and later. Use the Global Logger on earlier operating systems.
You use the registry to configure the AutoLogger session. Add the following registry key, if it is not already present:
HKEY_LOCAL_MACHINE
\SYSTEM
\CurrentControlSet
\Control
\WMI
\Autologger
Under the Autologger key create a key for each AutoLogger session that you want to configure as shown in the following example.
HKEY_LOCAL_MACHINE
\SYSTEM
\CurrentControlSet
\Control
\WMI
\Autologger
\Logger Session A
\Logger Session B
\Logger Session C
For each session, create a key for each provider that you want to enable to the session. Use the provider's GUID as the key.
HKEY_LOCAL_MACHINE
\SYSTEM
\CurrentControlSet
\Control
\WMI
\Autologger
\Logger Session A
\{ProviderGuid1}
\{ProviderGuid2}
\Logger Session B
\Logger Session C
The following table describes the values that you can define for each AutoLogger session. You must have administrator privileges to specify these registry values. The Start and Guid value are the only values required to start the AutoLogger session; all other values have default settings that are used if the value is not present in the registry. Typically, you should use the default values. If you specify a value that ETW cannot support, ETW will override the value.
| Value | Type | Description |
|---|---|---|
| BufferSize | REG_DWORD | The size of each buffer, in kilobytes. Should be less than one megabyte. ETW uses the size of physical memory to calculate this value. |
| ClockType | REG_DWORD | The timer to use when logging the time stamp for each event.
The default value is 1 (performance counter value) on Windows Vista and later. Prior to Windows Vista, the default value is 2 (system timer). |
| DisableRealtimePersistence | REG_DWORD | To disable real time persistence, set this value to 1. The default is 0 (enabled) for real time sessions. If real time persistence is enabled, real-time events that were not delivered by the time the computer was shutdown will be persisted. The events will then be delivered to the consumer the next time the consumer connects to the session. |
| FileCounter | REG_DWORD | Do not set or modify this value. This value is the serial number used to increment the log file name if FileMax is specified. If the value is not valid, 1 will be assumed. |
| FileName | REG_SZ | The fully qualified path of the log file. The path to this file must exist. The log file is a sequential log file. The path is limited to 1024 characters. If FileName is not specified, events are written to %SystemRoot%\System32\LogFiles\WMI<sessionname>.etl. |
| FileMax | REG_DWORD | The maximum number of instances of the log file that ETW creates. If the log file specified in FileName exists, ETW appends the FileCounter value to the file name. For example, if the default log file name is used, the form is %SystemRoot%\System32\LogFiles\WMI<sessionname>.etl.NNNN. The first time the computer is started, the file name is <sessionname>.etl.0001, the second time the file name is <sessionname>.etl.0002, and so on. If FileMax is 3, on the fourth restart of the computer, ETW resets the counter to 1 and overwrites <sessionname>.etl.0001, if it exists. The maximum number of instances of the log file that are supported is 16. Do not use this feature with the EVENT_TRACE_FILE_MODE_NEWFILE log file mode. |
| FlushTimer | REG_DWORD | 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 when a buffer is full and when the trace session stops. For the case of a real-time logger, a value of zero (the default value) means that the flush time will be set to 1 second. A real-time logger is when LogFileMode is set to EVENT_TRACE_REAL_TIME_MODE. The default value is 0. By default, buffers are flushed only when they are full. |
| Guid | REG_SZ | A string that contains a GUID that uniquely identifies the session. This value is required. |
| LogFileMode | REG_DWORD | Specify one or more log modes. For possible values, see Logging Mode Constants. The default is EVENT_TRACE_FILE_MODE_SEQUENTIAL. Instead of writing to a log file, you can specify either EVENT_TRACE_BUFFERING_MODE or EVENT_TRACE_REAL_TIME_MODE. Specifying EVENT_TRACE_BUFFERING_MODE avoids the cost of flushing the contents of the session to disk when the file system becomes available. Note that using EVENT_TRACE_BUFFERING_MODE will cause the system to ignore the MaximumBuffers value, as the buffer size is instead the product of MinimumBuffers and BufferSize. AutoLogger sessions do not support the EVENT_TRACE_FILE_MODE_NEWFILE logging mode. If EVENT_TRACE_FILE_MODE_APPEND is specified, BufferSize must be explicitly provided and must be the same in both the logger and the file being appended. |
| MaxFileSize | REG_DWORD | The maximum file size of the log file, in megabytes. The session is closed when the maximum size is reached, unless you are in circular log file mode. To specify no limit, set value to 0. The default is 100 MB, if not set. The behavior that occurs when the maximum file size is reached depends on the value of LogFileMode. |
| MaximumBuffers | REG_DWORD | The maximum number of buffers to allocate. 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. |
| MinimumBuffers | REG_DWORD | The minimum number of buffers to allocate at startup. 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. |
| Start | REG_DWORD | To have the AutoLogger session start the next time the computer is restarted, set this value to 1; otherwise, set this value to 0. |
| Status | REG_DWORD | The startup status of the AutoLogger. If the AutoLogger failed to start, the value of this key is the appropriate Win32 error code. If the AutoLogger successfully started, the value of this key is ERROR_SUCCESS (0). |
| Boot | REG_DWORD | This feature should not be used outside of debugging scenarios. If this registry key is set to 1, the autologger will be started earlier than normal during kernel initialization, allowing it to capture events during the initialization of many important kernel subsystems. However, enabling this option has a negative impact on boot times and imposes additional restrictions on the autologger. If this feature is enabled, the autologger session GUID must be populated, and many other autologger settings may not work. This key is supported on Windows Server 2022 and later. |
The following table describes the values that you can define for each provider that you want to enable to your session. You must have administrator privileges to specify these registry values. If you specify a value that ETW cannot support, ETW will override the value.
| Value | Type | Description |
|---|---|---|
| Enabled | REG_DWORD | Determines if the provider is enabled. To enable the provider, set this value to 1. To disable the provider, set this value to 0. The default is 0. |
| EnableFlags | REG_DWORD | Provider-defined value that specifies the class of events for which the provider generates events. For details, see the EnableFlags parameter of the EnableTrace function. Specify this value name if the provider does not support MatchAnyKeyword or MatchAllKeyword. |
| EnableLevel | REG_DWORD | Provider-defined value that specifies the level of detail included in the event. For example, you can use this value to indicate the severity level of the events (informational, warning, error) that the provider generates. For a list of predefined levels, see the level parameter of the EnableTraceEx function. |
| EnableProperty | REG_DWORD | Use this value to include one or more of the following items in the log file:
|
| MatchAnyKeyword | REG_QWORD | Bitmask of keywords that determine the category of events that you want the provider to write. The provider writes the event if any of the event's keyword bits match any of the bits set in this mask. To specify that the provider write all events, set this value to zero. For an example, see the Remarks section of the EnableTraceEx function. |
| MatchAllKeyword | REG_QWORD | This bitmask is optional. This mask further restricts the category of events that you want the provider to write. If the event's keyword meets the MatchAnyKeyword condition, the provider will write the event only if all of the bits in this mask exist in the event's keyword. This mask is not used if MatchAnyKeyword is zero. For an example, see the Remarks section of the EnableTraceEx function. |
After the registry has been modified, the AutoLogger session is started the next time the computer is restarted. The AutoLogger session calls the EnableTraceEx function to enable the providers.
The AutoLogger sessions increase the system boot time and should be used sparingly. Services that want to capture information during the boot process should consider adding controller logic to itself instead of using the AutoLogger session.
To stop an AutoLogger session, call the ControlTrace function. The session name that you pass to the function is the name of the registry key that you used to define the session in the registry.
For details on starting an event tracing session, see Configuring and Starting an Event Tracing Session.
For details on starting a private logger session, see Configuring and Starting a Private Logger Session.
For details on starting an NT Kernel Logger session, see Configuring and Starting the NT Kernel Logger Session.