Export (0) Print
Expand All
Expand Minimize

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.

ValueMeaning
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 codeDescription
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 <provider-name>
  • Wevtutil gp <provider-name>

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 | Windows Store apps]

Minimum supported server

Windows 2000 Server [desktop apps | Windows Store apps]

Header

Evntrace.h

Library

Advapi32.lib

DLL

Advapi32.dll

See also

ControlCallback
EnableTraceEx
EnableTraceEx2
GetTraceEnableFlags
GetTraceEnableLevel
GetTraceLoggerHandle
StartTrace

 

 

Community Additions

ADD
Show:
© 2014 Microsoft