EnableTrace function (evntrace.h)
Enables or disables the specified classic event trace provider.
On Windows Vista and later, call the EnableTraceEx function to enable or disable a provider.
ULONG WMIAPI EnableTrace( ULONG Enable, ULONG EnableFlag, ULONG EnableLevel, LPCGUID ControlGuid, TRACEHANDLE TraceHandle );
If TRUE, the provider is enabled; otherwise, the provider is disabled.
Provider-defined value that specifies the class of events for which the provider generates events. A provider that generates only one class of events will typically ignore this flag. If the provider is more complex, the provider could use the TraceGuidReg parameter of RegisterTraceGuids to register more than one class of events. For example, if the provider has a database component, a UI component, and a general processing component, the provider could register separate event classes for these components. This would then allow the controller the ability to turn on tracing in only the database component.
Provider-defined value that specifies the level of information the event generates. For example, you can use this value to indicate the severity level of the events (informational, warning, error) you want the provider to generate.
Specify a value from zero to 255. ETW defines the following severity levels that you can use. Higher numbers imply that you get lower levels as well. For example, if you specify TRACE_LEVEL_WARNING, you also receive all warning, error, and fatal events.
GUID of the event trace provider that you want to enable or disable.
Handle of the event tracing session to which you want to enable, disable, or change the logging level of the provider. The StartTrace function returns this handle.
If the function is successful, the return value is ERROR_SUCCESS.
If the function fails, the return value is one of the system error codes. The following table includes some common errors and their causes.
One of the following is true:
||You cannot change the enable flags and level when the provider is not registered.|
||The provider is not registered. Occurs when KB307331 or Windows 2000 Service Pack 4 is installed and the provider is not registered. To avoid this error, the provider must first be registered.|
||Exceeded the number of trace sessions that can enable the provider.|
Only users with administrative privileges, users in the Performance Log Users group, and services running as LocalSystem, LocalService, NetworkService can enable trace providers. To grant a restricted user the ability to enable a trace provider, add them to the Performance Log Users group or see EventAccessControl.
Windows XP and Windows 2000: Anyone can enable a trace provider.
Event trace controllers call this function.
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 session tried to enable a classic provider, the first session would stop receiving events when the second session enabled the same 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.
The provider remains enabled for the session until the session disables the provider. If the application that started the session ends without disabling the provider, the provider remains enabled.
The EnableTrace function calls the ControlCallback function implemented by the event trace provider, if defined. The provider defines its interpretation of being enabled or disabled. Typically, if a provider has been enabled, it generates events, but while it is disabled, it does not. The ControlCallback function can call the GetTraceEnableFlags, GetTraceEnableLevel, and GetTraceLoggerHandle functions to obtain the values specified for the EnableFlag, EnableLevel, and SessionHandle parameters, respectively.
You can call this function one time to enable a provider before the provider registers itself. After the provider registers itself, ETW calls the provider's ControlCallback function. If you try to enable the provider for multiple sessions before the provider registers itself, ETW will only enable the provider for the last session. For example, if you enable the provider to Session A and then enable the provider to Session B, when the provider registers itself, the provider is only enabled for Session B.
You do not call EnableTrace to enable kernel providers. To enable kernel providers, set the EnableFlags member of EVENT_TRACE_PROPERTIES which you then pass to StartTrace. The StartTrace function enables the selected kernel providers.
To determine the level and keywords used to enable a manifest-based provider, use one of the following commands:
- Logman query providers <provider-name>
- Wevtutil gp <provider-name>
If you use EnableTrace to enable a manifest-based provider, the following translation occurs:
- The EnableLevel parameter is the same as setting the Level parameter in EnableTraceEx.
- The EnableFlag is the same as setting the MatchAnyKeyword parameter in EnableTraceEx.
- In the EnableCallback callback, the SourceId parameter will be NULL, Level will be set to the value in EnableTrace, MatchAnyKeyword will be set to the value of EnableFlag in EventTrace, MatchAllKeyword will be 0, and FilterData will be NULL.
On Windows 8.1,Windows Server 2012 R2, and later, payload filters can be used by the EnableTraceEx2 function to filter on specific conditions in a logger session.
For an example that uses EnableTrace, see Example that Creates a Session and Enables a manifest-based provider.
|Minimum supported client||Windows 2000 Professional [desktop apps | UWP apps]|
|Minimum supported server||Windows 2000 Server [desktop apps | UWP apps]|