Configuring and Starting an Event Tracing Session
To configure an event tracing session, use the EVENT_TRACE_PROPERTIES structure to specify the properties of the session. The memory you allocate for the EVENT_TRACE_PROPERTIES structure must be large enough to also contain the session and log file names that follow the structure in memory.
After you specify the properties of the session, call the StartTrace function to start the session. If the function succeeds, the SessionHandle parameter will contain the session handle, and the LoggerNameOffset property will contain the offset to the name of the session.
To enable the providers that you want to log events to your session, call the EnableTrace function to enable classic providers and the EnableTraceEx function to enable manifest-based providers. To enable providers that you want log events to your session filtering on specific conditions on Windows 8.1,Windows Server 2012 R2, and later, call the EnableTraceEx2 function.
In addition, you can also trace additional information on an event with a call to the TraceSetInformation function. TraceSetInformation puts additional trace information into the extended data section of an event, and can include information such as the trace version info, or what providers are currently registered on the system. For more information, see Retrieving Additional Event Tracing Data.
Up to eight trace sessions can enable and receive events from the same manifest-based provider. However, only one trace session can enable a classic provider. If more than one trace session tries to enable a classic provider, the first session would stop receiving events when the second session enables the provider. For example, if Session A enabled Provider 1 and then Session B enabled Provider 1, only Session B would receive events from Provider 1.
You can use any of the three functions to enable a provider but you may lose functionality if you use EnableTrace to enable a manifest-based provider because you will not be able to provide a MatchAllKeyword value, specify extended data items to include in the event, or provide provider-defined filter data. For more information, see the Remarks section of each function.
On Windows 8.1,Windows Server 2012 R2, and later, event payload , scope, and stack walk filters can be used by the EnableTraceEx2 function and the ENABLE_TRACE_PARAMETERS and EVENT_FILTER_DESCRIPTOR structures to filter on specific conditions in a logger session. For more information on event payload filters, see the TdhCreatePayloadFilter, and TdhAggregatePayloadFilters functions and the ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTOR, and PAYLOAD_FILTER_PREDICATE structures.
To determine the level and keywords used to enable a manifest-based provider, use one of the following commands:
- Logman query provider-name
- Wevtutil gp provider-name
The commands list the level and keywords only, the provider must document any filter data requirements for potential controllers.
To enumerate the manifest-based providers use Wevtutil ep.
For classic providers, it is up to the provider to document and make available to potential controllers the severity levels or enable flags that it supports. If the provider wants to be enabled by any controller, the provider should accept 0 for the severity level and enable flags and interpret 0 as a request to perform default logging (whatever that may be).
You can enable the provider before or after the provider registers itself. After enabling the provider, ETW will then call the provider's callback function. If the provider is not registered, ETW will call the provider's callback function after it registers itself.
You can also use the EnableTrace function to disable the provider (stop it from logging events to your session) or to update the logging level or enable flags of the provider. With the EnableTraceEx function, you can disable the provider or update the level, keywords, extended data and filter data. Each time you call the EnableTrace or EnableTraceEx function, ETW calls the provider's callback function. The provider remains enabled for the session until the session disables the provider.
To stop the trace session after collecting events, call the ControlTrace function and pass EVENT_TRACE_CONTROL_STOP as the control code. To specify the session to stop, you can pass the event tracing session handle obtained from an earlier call to the StartTrace function, or the name of a previously started session. Be sure to disable all providers before stopping the session. If you stop the session before first disabling the provider, ETW will disable the provider and try to call the provider's control callback function. If the application that started the session ends without disabling the provider or calling the ControlTrace function, the provider remains enabled.
If ControlTrace is successful, the session properties are updated to reflect the final property values and run statistics for the event tracing session.
For an example that starts an event tracing session, see the following:
- Example that Creates a Session and Enables a Manifest-based Provider - starts a trace session, enables a manifest-based provider, disables the provider and then stops the session.
For details on starting a trace session, see one of the following:
- Configuring and Starting a SystemTraceProvider Session
- Configuring and Starting the NT Kernel Logger Session
- Configuring and Starting an AutoLogger Session
- Configuring and Starting the Global Logger Session
- Configuring and Starting a Private Logger Session
Related topics
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for