EventProvider

Article
10/06/2022

Configures the Event Tracing for Windows (ETW) user-mode provider.

Element Hierarchy

<WindowsPerformanceRecorder>
- <Profiles>
  - <EventProvider>
  - <Profile>
    - <Collectors>
      - <EventCollectorId>
        
        <EventProviders>
        
        <EventProvider>

Syntax

<EventProvider Id               = IdType
               Name             = string
               Base             = string
               NonPageMemory    = boolean
               Stack            = boolean
               SID              = boolean
               TSID             = boolean
               Level            = unsigendByte
               CaptureStateOnly = boolean
               Strict           = boolean
               ProcessExeFilter = string
               EventKey         = boolean
               ExcludeInPrivate = boolean>

  <!-- Child elements -->
  Keywords,
  CaptureStateOnStart,
  CaptureStateOnSave,
  CaptureStateOnDemand,
  Stacks,
  EventFilters,
  StackFilters,
  EventNameFilters,
  StackEventNameFilters,
  StackKeywordLevelFilter
</EventProvider>

Attributes and Elements

Attributes

Attribute	Description	Data type	Required	Default
Id	Uniquely identifies the event provider.	String that must have at least one character and cannot contain colons (:) or spaces.	Yes
Name	The name of the event provider.	This attribute can have one of the following values: A registered Crimson provider, for example, "Microsoft-Windows-Search-Core". A provider GUID, for example "49c2c27c-fe2d-40bf-8c4e-c3fb518037e7". The name of a legacy provider, for example "IE6". A special-case name, such as "PerfTrack" or "DotNetProvider".	Yes
ProcessExeFilter	Filters an event based on the process .exe name specified. Sets the filter data in EVENT_FILTER_DESCRIPTOR.	This is an optional attribute you add to the EventProvider ID in the WPR profile. For example: "ProcessExeFilter="wpa.exe"	No
Base	Indicates the base for the provider.	string	No
NonPagedMemory	Use non-paged memory for a tracing session.	boolean	No	false
Stack	Capture stacks with the event	boolean	No	false
SID	Include the security identifier (SID) of the user in the extended data of logged events. Sets EVENT_ENABLE_PROPERTY_SID.	boolean	No	false
TSID	Include the terminal session identifier in the extended data of logged events. Sets EVENT_ENABLE_PROPERTY_TS_ID.	boolean	No	false
Level	Indicates the level value.	unsignedByte	No	Zero, which ETW treats as 0xFF.
CaptureStateOnly	Enabled the provider only at start or save of a tracing session.	boolean	No	false
Strict	Fail the trace recording if the provider fails to be enabled.	boolean	No	false
EventKey	Include the Event Key in the extended data and sets EVENT_ENABLE_PROPERTY_EVENT_KEY flag.	boolean	No	false
ExecludeInPrivate	Filter out all events that are marked as an InPrivate event or come from InPrivate process. Sets EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE flag	boolean	No	false
EnableSilos	Enables host logging sessions to collect Crimson events from server silos. Sets EVENT_ENABLE_PROPERTY_ENABLE_SILOS flag.	boolean	No	false
ContainerId	Marks the provider's events with source container information. Sets EVENT_ENABLE_PROPERTY_SOURCE_CONTAINER_TRACKING flag.	boolean	No	false

Child Elements

Element	Description	Requirement
Keywords (in EventProvider)	Represents a collection of Keyword (in EventProvider) elements.	Optional, 1 or more.
CaptureStateOnStart	Represents a collection of Keyword (in EventProvider) elements for events to be captured at the start of a trace.	Optional, zero or 1.
CaptureStateOnSave	Represents a collection of Keyword (in EventProvider) elements for events to be captured when a trace is saved.	Optional, zero or 1.
CaptureStateOnDemand	Represents a collection of Keyword (in EventProvider) elements for events to be captured when user triggers with `wpr -capturestateondemand` command.	Optional, zero or 1.
Stacks	Represents a collection of stacks. For UMGL providers.	Optional, exactly 1.
EventFilters	Represents a collection of event Id filters.	Optional, exactly 1.
StackFilters	Represents a collection of stack filters by event Id.	Optional, exactly 1.
EventNameFilters	Represents a collection of event name filters.	Optional, exactly 1.
StackEventNameFilters	Represents a collection of stack filters by event name.	Optional, exactly 1.
StackKeywordLevelFilter	Represents a collection of stack filters by keyword and level	Optional, exactly 1.

Parent Elements

Element	Description
EventProviders	Represents a collection of EventProvider elements.
Profiles	Represents a collection of collectors, providers, and profiles.

Remarks

Provider definition order is important. Definitions must appear in the following order in the .wprp file:

Collectors
System provider
Event provider(s)

Optional inner XML tags specify what keywords to enable. Unlike for system providers, there are no textual constants defined for event providers, so hexadecimal-style strings must be used. However, the syntax is the same as for system provider. If no keywords are specified, the default value of zero is used (which is treated by ETW as the string 0xFFFFFFFFFFFFFFFF).

Derived event providers have all the attributes of the base provider by default. They can be overridden by explicitly specifying them in the derived provider. For more information, see Inheritance.

Example

The following example defines two event providers.

<EventProvider
  Id="Win32K-provider"
  Name="Microsoft-Windows-Win32K"
  NonPagedMemory="true"
  Stack="true"> 
  <Keywords>
    <Keyword
      Value="0x240000"/>
  </Keywords>
</EventProvider>

<EventProvider
  Id="Search-Core-provider"
  Name="Microsoft-Windows-Search-Core"/>

The following code examples define capture-state providers.

<EventProvider Id="sample-provider" Name="SampleProvider" NonPagedMemory="true" Level="5">
  <Keywords>
    <Keyword Value="0x98"/> <!-- Provider is enabled with these keywords throughout the tracing session. -->
  </Keywords>
  <CaptureStateOnStart>
    <Keyword Value="0xff4"/> <!-- Provider is enabled with these keywords when tracing is started. -->
  </CaptureStateOnStart>
  <CaptureStateOnSave>
    <Keyword Value="0x118"/> <!-- Provider is enabled with these keywords when tracing is saved. -->
  </CaptureStateOnSave>
</EventProvider>

<EventProvider Id="EventProvider_DWMWin32k_CaptureState" Name="e7ef96be-969f-414f-97d7-3ddb7b558ccc" NonPagedMemory="true" CaptureStateOnly="true" > 
  <!-- CaptureStateOnly="true" means that provider is not enabled throughout the tracing session. -->
  <CaptureStateOnSave>
    <Keyword Value="0x80000"/> <!-- Provider is enabled with these keywords when tracing is saved. -->
  </CaptureStateOnSave>
</EventProvider>

For managed scenarios, use the following event provider definition:

<EventCollectorId Value ="ExampleEventCollector">
  <EventProviders>
    <EventProviderId Value="EventProvider_DotNetProvider" /> <!-- You can use this provider in the profile definition because the provider is declared in the built-in profile -->
    <EventProviderId Value="Another_Example_Provider" />
    </EventProvider>
  </EventProviders>
</EventCollectorId>

Elements