Bewerken

Delen via


Configuring and Starting the Global Logger Session

The Global Logger event tracing session records events that occur early in the operating system boot process. Applications and device drivers can use the Global Logger 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 Global Logger session begins.

Note

If you are creating a Global Logger session on Windows Vista, you should consider creating an AutoLogger session instead.

You use the registry to configure the Global Logger session. Add the GlobalLogger key to the following registry key, if it is not already present:

HKEY_LOCAL_MACHINE
   \SYSTEM
      \CurrentControlSet
         \Control
            \WMI

The following table describes the values that you can define for the GlobalLogger key. You must have administrator privileges to specify these registry values. The registry values affect all providers that log events to the Global Logger session. The Start value is the only value required to start the Global Logger 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
Start REG_DWORD Set this value to 1 (on) to start the Global Logger session the next time the system starts. To stop the session from starting, set this value to 0 (off).
BufferSize REG_DWORD The size of each buffer, in kilobytes. This value 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.
  • 1 = Performance counter value (high resolution)
  • 2 = System timer
  • 3 = CPU cycle counter
For a description of each clock type, see the ClientContext member of WNODE_HEADER.
The default value is 1 (performance counter value) on Windows Vista and later. Prior to Windows Vista, the default value is 2 (system timer).
EnableKernelFlags REG_BINARY Use this value to enable one or more kernel providers. If you enable kernel providers, the Global Logger session will rename itself to NT Kernel Logger when it starts. For possible values, see the EnableFlags member of EVENT_TRACE_PROPERTIES.
FileCounter REG_DWORD The number of event trace log files generated by Global Logger sessions. The system increments this value until it reaches the value of FileMax. Then, it resets the value to 0. This counter prevents the system from overwriting a Global Logger trace log file.
FileMax REG_DWORD The maximum number of event trace log files permitted on the system. When the number of trace logs reaches the specified maximum, the system begins to overwrite the logs, beginning with the oldest.
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\GlobalLogger.etl.NNNN.
The default value is 0, meaning that there is no maximum.
FileName REG_SZ Fully qualified path of the log file. The path to this file must exist. The log file is a sequential log file. Note that all providers writing events to the Global Logger session write events to this log file. The path is limited to 1024 characters.If FileName is not specified, events are written to %SystemRoot%\System32\LogFiles\WMI\GlobalLogger.etl. Prior to Windows Vista: The default file is %SystemRoot%\System32\LogFiles\WMI\Trace.log.

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.
LogFileMode REG_DWORD Specifies log session options. For values, see Logging Mode Constants. This values is supported on Windows Vista and later.
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.
MaxFileSize REG_DWORD The maximum size, in megabytes, of the event trace log file. By default, there is no maximum file size.
MinimumBuffers REG_DWORD The minimum number of buffers to allocate when the Global Logger session starts. 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.
The default value on a single-processor system is 0x3.
Status REG_DWORD The startup status of the Global Logger. If the Global Logger failed to start, the value of this key is the appropriate Win32 error code. If the Global Logger successfully started, the value of this key is ERROR_SUCCESS (0).

After the registry has been modified and the computer restarted, the Global Logger session starts automatically and is used like any other session with one exception: You use the WMI_GLOBAL_LOGGER_ID constant handle (defined in Wmistr.h) to reference the Global Logger session. This constant may be used as an argument to any event tracing function that accepts a session handle. In functions that accept a session name, use GLOBAL_LOGGER_NAME.

The Global Logger controller does not call the EnableTrace function to enable providers. The provider is responsible for determining if the Global Logger session is started and then enabling itself.

To determine if the Global Logger session is started, you can call the ControlTrace function, setting SessionHandle to WMI_GLOBAL_LOGGER_ID and ControlCode to EVENT_TRACE_CONTROL_QUERY. If the ControlTrace call is successful, the Global Logger session exists and the provider can enable itself and log events to the Global Logger session (the ControlTrace function returns ERROR_WMI_INSTANCE_NOT_FOUND if the Global Logger is not active).

Typically, the controller is responsible for passing the enable flags and level to the provider when it enables the provider, but because the Global Logger controller does not enable the provider, it is the provider's responsibility to pass this information to itself, if needed.

The Global Logger session is a limited resource 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 Global Logger session.

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.