EnableTrace function

Enables or disables the specified classic event trace provider.

On Windows Vista and later, call the EnableTraceEx function to enable or disable a provider.

Syntax

ULONG EnableTrace(
  _In_ ULONG       Enable,
  _In_ ULONG       EnableFlag,
  _In_ ULONG       EnableLevel,
  _In_ LPCGUID     ControlGuid,
  _In_ TRACEHANDLE SessionHandle
);

Parameters

Enable [in]

If TRUE, the provider is enabled; otherwise, the provider is disabled.

EnableFlag [in]

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.

The provider calls GetTraceEnableFlags from its ControlCallback function to obtain the enable flags.

EnableLevel [in]

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.

Value Meaning
TRACE_LEVEL_CRITICAL
1
Abnormal exit or termination events
TRACE_LEVEL_ERROR
2
Severe error events
TRACE_LEVEL_WARNING
3
Warning events such as allocation failures
TRACE_LEVEL_INFORMATION
4
Non-error events such as entry or exit events
TRACE_LEVEL_VERBOSE
5
Detailed trace events

 

ControlGuid [in]

GUID of the event trace provider that you want to enable or disable.

SessionHandle [in]

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.

Return value

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.

Return code Description
ERROR_INVALID_PARAMETER
One of the following is true:
  • ControlGuid is NULL.
  • SessionHandle is NULL.
ERROR_INVALID_FUNCTION
You cannot change the enable flags and level when the provider is not registered.
ERROR_WMI_GUID_NOT_FOUND
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.
ERROR_NO_SYSTEM_RESOURCES
Exceeded the number of trace sessions that can enable the provider.
ERROR_ACCESS_DENIED
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.

 

Remarks

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
  • Wevtutil gp

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).

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.

Examples

For an example that uses EnableTrace, see Example that Creates a Session and Enables a manifest-based provider.

Requirements

Minimum supported client
Windows 2000 Professional [desktop apps | UWP apps]
Minimum supported server
Windows 2000 Server [desktop apps | UWP apps]
Header
Evntrace.h
Library
Advapi32.lib
DLL
Advapi32.dll

See also

ControlCallback

EnableTraceEx

EnableTraceEx2

GetTraceEnableFlags

GetTraceEnableLevel

GetTraceLoggerHandle

StartTrace