Export (0) Print
Expand All

ENABLE_TRACE_PARAMETERS structure

The ENABLE_TRACE_PARAMETERS structure defines the information used to enable a provider.

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.

EnableProperty

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 in the extended data the security identifier (SID) of the user.

EVENT_ENABLE_PROPERTY_TS_ID

Include in the extended data the terminal session identifier.

EVENT_ENABLE_PROPERTY_STACK_TRACE

Include in the extended data a call stack trace for events written using EventWrite.

If you set EVENT_ENABLE_PROPERTY_STACK_TRACE, 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, 32-bit processes will receive 64-bit stack traces.

 

ControlFlags

Reserved. Set to 0.

SourceId

A GUID that uniquely identifies the session 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 filter for a specific filter type as specified by the Type member of the EVENT_FILTER_DESCRIPTOR structure.

For a schematized filter (a Type member equal to EVENT_FILTER_TYPE_SCHEMATIZED), the provider uses 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 schematized filter to the provider.

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

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 for use with the EnableTraceEx2 function.

On 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

You should consider the cost of setting this registry value before doing so.

Requirements

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Evntrace.h

See also

EnableTraceEx2
ENABLE_TRACE_PARAMETERS_V1
EVENT_FILTER_DESCRIPTOR
EVENT_FILTER_EVENT_ID
PAYLOAD_FILTER_PREDICATE
TdhAggregatePayloadFilters
TdhCreatePayloadFilter
TdhEnumerateProviderFilters

 

 

Community Additions

ADD
Show:
© 2014 Microsoft