EVENT_FILTER_DESCRIPTOR structure

The EVENT_FILTER_DESCRIPTOR structure defines the filter data that a session passes to the provider's enable callback function.

Syntax


typedef struct _EVENT_FILTER_DESCRIPTOR {
  ULONGLONG Ptr;
  ULONG     Size;
  ULONG     Type;
} EVENT_FILTER_DESCRIPTOR, *PEVENT_FILTER_DESCRIPTOR;

Members

Ptr

A pointer to the filter data for the filter type specified in the Type member.

If the Type member is set to EVENT_FILTER_TYPE_PID, the Ptr member points to an array of process IDs (PIDs). For other values of the Type member, the Ptr member points to a single structure or entry, not an array.

If the Type member is set to EVENT_FILTER_TYPE_EVENT_ID, the Ptr member points to a EVENT_FILTER_EVENT_ID structure that contains an array of event IDs and a Boolean value that determines whether tracing is enabled or disabled for the specified event IDs.

If the Type member is set to EVENT_FILTER_TYPE_STACKWALK, the Ptr member points to a EVENT_FILTER_EVENT_ID structure that contains an array of event IDs and a Boolean value that determines whether stack tracing is enabled or disabled for the specified event IDs.

If the Type member is set to EVENT_FILTER_TYPE_SCHEMATIZED, see the EVENT_FILTER_HEADER structure for details on constructing the filter.

Size

The size of the data, in bytes.

The maximum data size limit varies based on the specified Type member (the type of the filter). The maximum data size, in bytes, for many of the filter types is limited to MAX_EVENT_FILTER_DATA_SIZE defined in the evntprov.h header file to 1024.

Type

A provider-defined value that identifies the filter. For filters defined in an instrumentation manifest, set this member to EVENT_FILTER_TYPE_SCHEMATIZED.

The possible values for this member are defined in the Evntprov.h header file.

ValueMeaning
EVENT_FILTER_TYPE_NONE
0x00000000

No filters.

EVENT_FILTER_TYPE_SCHEMATIZED
0x80000000

A schematized filter.

This is the traditional filtering setup also called provider-side filtering. The controller defines a custom set of filters as a binary object that is passed to the provider in the EnableTrace, EnableTraceEx, or EnableTraceEx2 call. It is incumbent on the controller and provider to define and interpret these filters and the controller should only log applicable events. This requires a close coupling of the controller and provider since the type and format of the binary object of what can be filtered is not defined. The TdhEnumerateProviderFilters function can be used to retrieve the filters defined in a manifest.

For more information on schematized filters, see Defining Filters.

EVENT_FILTER_TYPE_SYSTEM_FLAGS
0x80000001

Reserved for internal use.

EVENT_FILTER_TYPE_TRACEHANDLE
0x80000002

Used to capture a rundown of a particular trace session. The ControlCode parameter passed to the EnableTraceEx function must be set to EVENT_CONTROL_CODE_CAPTURE_STATE and the ProviderId parameter must be the SystemTraceControlGuid. The EVENT_FILTER_DESCRIPTOR structure should point to a single TRACEHANDLE that represents a current ETW session. A rundown will be performed for that particular session.

EVENT_FILTER_TYPE_PID
0x80000004

The process ID. This is one of the scope filters.

Filtering ETW events based on process IDs will result in an event stream (file or real-time) that contains the events from the providers in the specified processes only. It will only enable the provider in the processes whose PIDs are provided. The list of PIDs is the PIDs of the processes running at the time when EnableTraceEx2 is called and will enable the provider in all the processes (for which PIDs are provided) at that particular time. The list of PIDs will not be stored in the session. So when a process is terminated and then reappears, the provider in it will not get automatically enabled to the trace session. The PIDs based filter-blob is only valid for a kernel mode logger session because the private logger session runs inside a user-mode process.

The maximum number of process IDs that can be filtered is limited by MAX_EVENT_FILTER_PID_COUNT defined in the evntprov.h header file to 8.

In case a process ID filter is provided, then the provider will be enabled in the user-mode processes only. In case, the same provider is registered by a kernel-mode driver, it will not be enabled.

EVENT_FILTER_TYPE_EXECUTABLE_NAME
0x80000008

The executable file name. This is one of the scope filters.

EVENT_FILTER_TYPE_PACKAGE_ID
0x80000010

The package ID. This is one of the scope filters

This can be used to filter providers to events emitted from a particular Windows Store app package.

EVENT_FILTER_TYPE_PACKAGE_APP_ID
0x80000020

The package relative app ID (PRAID). This is one of the scope filters

This can be used to filter providers to events emitted from a particular Windows Store app package.

EVENT_FILTER_TYPE_PAYLOAD
0x80000100

The event payload (the content of the event).

The maximum data size, in bytes, for an event payload filter is limited to MAX_EVENT_FILTER_PAYLOAD_SIZE defined in the evntprov.h header file to 4096.

EVENT_FILTER_TYPE_EVENT_ID
0x80000200

The event ID. This is one of the scope filters.

This feature allows enabling or disabling filtering for a list of events. The provided filter includes a EVENT_FILTER_EVENT_ID structure that contains an array of event IDs and a Boolean value that indicates whether to enable or disable from filtering for the specified events. Each event write call will go through this array quickly to find out whether enable or disable logging the event.

The maximum number of event IDs allowed in the EVENT_FILTER_EVENT_ID structure is limited by MAX_EVENT_FILTER_EVENT_ID_COUNT defined in the evntprov.h header file to 64.

EVENT_FILTER_TYPE_STACKWALK
0x80001000

A stack walk.

When stack walking is enabled for a provider, then the stack is captured for all the events generated by the provider. Most of the time, the user is only interested in stack from only certain number of events.

This feature allows enabling or disabling stack walking on a list of events. The provided filter includes a EVENT_FILTER_EVENT_ID structure that contains an array of event IDs and a Boolean value that indicates whether to enable or disable stack capturing for the specified events. Each event write call will go through this array quickly to find out whether the stack should be captured or not.

The maximum number of event IDs allowed in the EVENT_FILTER_EVENT_ID structure is limited by MAX_EVENT_FILTER_EVENT_ID_COUNT defined in the evntprov.h header file to 64.

 

Remarks

The provider determines the layout of the data and its purpose.

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 ENABLE_TRACE_PARAMETERS and PAYLOAD_FILTER_PREDICATE structures.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Evntprov.h

See also

Defining Filters
EnableCallback
EnableTrace
EnableTraceEx
EnableTraceEx2
ENABLE_TRACE_PARAMETERS
EVENT_FILTER_EVENT_ID
PAYLOAD_FILTER_PREDICATE
TdhAggregatePayloadFilters
TdhCreatePayloadFilter

 

 

Community Additions

ADD
Show:
© 2014 Microsoft