Export (0) Print
Expand All
Expand Minimize

EnableTraceEx function

Enables or disables the specified event trace provider.

The EnableTraceEx2 function supersedes this function.

Syntax


ULONG EnableTraceEx(
  _In_      LPCGUID ProviderId,
  _In_opt_  LPCGUID SourceId,
  _In_      TRACEHANDLE TraceHandle,
  _In_      ULONG IsEnabled,
  _In_      UCHAR Level,
  _In_      ULONGLONG MatchAnyKeyword,
  _In_      ULONGLONG MatchAllKeyword,
  _In_      ULONG EnableProperty,
  _In_opt_  PEVENT_FILTER_DESCRIPTOR EnableFilterDesc
);

Parameters

ProviderId [in]

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

SourceId [in, optional]

GUID that uniquely identifies the session that is enabling or disabling the provider. Can be NULL. If the provider does not implement EnableCallback, the GUID is not used.

TraceHandle [in]

Handle of the event tracing session to which you want to enable or disable the provider. The StartTrace function returns this handle.

IsEnabled [in]

Set to 1 to receive events when the provider is registered; otherwise, set to 0 to no longer receive events from the provider.

Level [in]

Provider-defined value that specifies the level of detail included in the event. Specify one of the following levels that are defined in Winmeta.h. 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 critical 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

 

MatchAnyKeyword [in]

Bitmask of keywords that determine the category of events that you want the provider to write. The provider writes the event if any of the event's keyword bits match any of the bits set in this mask. See Remarks.

MatchAllKeyword [in]

This bitmask is optional. This mask further restricts the category of events that you want the provider to write. If the event's keyword meets the MatchAnyKeyword condition, the provider will write the event only if all of the bits in this mask exist in the event's keyword. This mask is not used if MatchAnyKeyword is zero. See Remarks.

EnableProperty [in]

Optional information that ETW can include when writing the event. The data is written to the extended data item section of the event. To include the optional information, specify one or more of the following flags; otherwise, set to zero.

ValueMeaning
EVENT_ENABLE_PROPERTY_SID

Include the security identifier (SID) of the user in the extended data.

EVENT_ENABLE_PROPERTY_TS_ID

Include the terminal session identifier in the extended data.

 

EnableFilterDesc [in, optional]

An EVENT_FILTER_DESCRIPTOR structure that points to the filter data. The provider uses to filter data to prevent events that match the filter criteria from being written to the session; the provider determines the layout of the data and how it applies the filter to the event's data. A session can pass only one filter to the provider.

A session can call the TdhEnumerateProviderFilters function to determine the filters that it can pass to the provider.

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:

  • ProviderId is NULL.
  • TraceHandle is NULL.
ERROR_INVALID_FUNCTION

You cannot update the level when the provider is not 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.

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.

To include all events that a provider provides, set MatchAnyKeyword to zero (for a manifest-based provider and 0xFFFFFFFF for a classic provider). To include specific events, set the MatchAnyKeyword mask to those specific events. For example, if the provider defines an event for its initialization and cleanup routines (set keyword bit 0), an event for its file operations (set keyword bit 1), and an event for its calculation operations (set keyword bit 2), you can set MatchAnyKeyword to 5 to receive initialization and cleanup events and calculation events.

If the provider defines more complex event keywords, for example, the provider defines an event that sets bit 0 for read and bit 1 for local access and a second event that sets bit 0 for read and bit 2 for remote access, you could set MatchAnyKeyword to 1 to receive all read events, or you could set MatchAnykeyword to 1 and MatchAllKeywords to 3 to receive local reads only.

If an event's keyword is zero, the provider will write the event to the session, regardless of the MatchAnyKeyword and MatchAllKeyword masks.

When you call EnableTraceEx the provider may or may not be registered. If the provider is registered, ETW calls the provider's callback function, if it implements one, and the session begins receiving events. If the provider is not registered, ETW will call the provider's callback function when it registers itself, if it implements one, and the session will begin receiving events. If the provider is not registered, the provider's callback function will not receive the source ID or filter data. You can call EnableTraceEx one time to enable a provider before the provider registers itself.

If the provider is registered and already enabled to your session, you can also use this function to update the Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty and EnableFilterDesc parameters that determine which events the provider writes.

You do not call EnableTraceEx 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.

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.

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 EnableTraceEx to enable a classic provider, the following translation occurs:

  • The Level parameter is the same as setting the EnableLevel parameter in EnableTrace.
  • The MatchAnyKeyword is the same as setting the EnableFlag parameter in EnableTrace except that the keyword value is truncated from a ULONGLONG to a ULONG value.
  • In the ControlCallback callback, the provider can call GetTraceEnableLevel to get the level and GetTraceEnableFlags to get the enable flag.
  • The other parameter are not used.

A provider can define filters that a session uses to filter events based on event data. With the level and keywords that you provide, ETW determines whether the event is written to the session but with filters, the provider uses the filter data to determine whether it writes the event to the session. For example, if the provider generates process events, it could define a data filter that filters process events based on the process identifier. If the identifier of the process did not match the identifier that you passed as filter data, the provider would prevent event from being written to your session.

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.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Evntrace.h

Library

Advapi32.lib

DLL

Advapi32.dll

See also

EnableTraceEx2

 

 

Community Additions

ADD
Show:
© 2014 Microsoft