ENABLE_TRACE_PARAMETERS structure (evntrace.h)

The ENABLE_TRACE_PARAMETERS structure contains information used to enable a provider via EnableTraceEx2.

Syntax

typedef struct _ENABLE_TRACE_PARAMETERS {
  ULONG                    Version;
  ULONG                    EnableProperty;
  ULONG                    ControlFlags;
  GUID                     SourceId;
  PEVENT_FILTER_DESCRIPTOR EnableFilterDesc;
  ULONG                    FilterDescCount;
} ENABLE_TRACE_PARAMETERS, *PENABLE_TRACE_PARAMETERS;

Members

Version

Set to ENABLE_TRACE_PARAMETERS_VERSION_2 (2).

EnableProperty

Optional settings that ETW can include when writing the event. Some settings write extra data to the extended data item section of each event. Other settings control which events will be included in the trace. To use these optional settings, specify one or more of the following flags. Otherwise, set to zero.

• EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0

  Filters out events where the event's keyword is 0.

  Supported on Windows 10, version 1507 and later. This is also supported on Windows 8.1 and Windows 7 with SP1 via a patch.

• EVENT_ENABLE_PROPERTY_PROVIDER_GROUP

  Indicates that this call to EnableTraceEx2 should enable a Provider Group rather than an individual Event Provider.

  Supported on Windows 10, version 1507 and later. This is also supported on Windows 8.1 and Windows 7 with SP1 via a patch.

• EVENT_ENABLE_PROPERTY_PROCESS_START_KEY

  Include the Process Start Key in the extended data.

  The Process Start Key is a sequence number that identifies the process. While the Process ID may be reused within a session, the Process Start Key is guaranteed to be unique in the current boot session.

  Supported on Windows 10, version 1507 and later. This is also supported on Windows 8.1 and Windows 7 with SP1 via a patch.

• EVENT_ENABLE_PROPERTY_EVENT_KEY

  Include the Event Key in the extended data.

  The Event Key is a unique identifier for the event instance that will be constant across multiple trace sessions listening to this event. It can be used to correlate simultaneous trace sessions.

  Supported on Windows 10, version 1507 and later.

• EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE

  Filters out all events that are either marked as an InPrivate event or come from a process that is marked as InPrivate.

  InPrivate implies that the event or process contains some data that would be considered private or personal. It is up to the process or event to designate itself as InPrivate for this to work.

  Supported on Windows 10, version 1507 and later.

• EVENT_ENABLE_PROPERTY_SID

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

  Supported on Windows Vista and later.

• EVENT_ENABLE_PROPERTY_TS_ID

  Include the terminal session identifier in the event's extended data.

  Supported on Windows Vista and later.

• EVENT_ENABLE_PROPERTY_STACK_TRACE

  Add a call stack trace to the extended data of events written using EventWrite.

  Note

  ETW will drop the event if the total event size exceeds 64K. If the provider is logging events close in size to 64K maximum, it is possible that enabling stack capture will cause the event to be lost.

  If the stack is longer than the maximum number of frames (192), the frames will be cut from the bottom of the stack.

  For consumers, the events will include the EVENT_EXTENDED_ITEM_STACK_TRACE32 or EVENT_EXTENDED_ITEM_STACK_TRACE64 extended item. Note that on 64-bit computers, the trace will contain both 64-bit stacks even if the trace was started by a 32-bit trace controller.

  Supported on Windows 7 and later.

ControlFlags

Reserved. Set to 0.

SourceId

A GUID that uniquely identifies the caller that is enabling or disabling the provider. If the provider does not implement EnableCallback, the GUID is not used.

EnableFilterDesc

A pointer to an array of EVENT_FILTER_DESCRIPTOR structures that points to the filter data. The number of elements in the array is specified in the FilterDescCount member. There can only be one descriptor for each filter type as specified by the Type member of the EVENT_FILTER_DESCRIPTOR structure.

FilterDescCount

The number of elements (filters) in the EVENT_FILTER_DESCRIPTOR array pointed to by EnableFilterDesc member.

The FilterDescCount member should match the number of EVENT_FILTER_DESCRIPTOR structures in the array pointed to by the EnableFilterDesc member.

Remarks

The ENABLE_TRACE_PARAMETERS structure is a version-2 structure and replaces the ENABLE_TRACE_PARAMETERS_V1 structure.

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 EnableTraceEx2, TdhCreatePayloadFilter, and TdhAggregatePayloadFilters functions and the EVENT_FILTER_DESCRIPTOR and PAYLOAD_FILTER_PREDICATE structures.

Typically, on 64-bit computers, you cannot capture the kernel stack in certain contexts when page faults are not allowed. To enable walking the kernel stack on x64, set the DisablePagingExecutive Memory Management registry value to 1. The DisablePagingExecutive registry value is located under the following registry key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management. This should only be done for temporary diagnosis purposes because it increases memory usage of the system.

Requirements

See also

EVENT_FILTER_DESCRIPTOR

EVENT_FILTER_EVENT_ID

PAYLOAD_FILTER_PREDICATE

EnableTraceEx2

TdhAggregatePayloadFilters

TdhCreatePayloadFilter

TdhEnumerateProviderFilters