This is the third post in a series about authoring custom profiles for Windows Performance Recorder (WPR).

In previous posts I have explained;

1. Part 1 – Introduced the simplest custom profile as an example, and explained what Profile, Collector, and Provider elements are.
2. Part 2 – Developed the simplest custom profile introduced in part 1 and added SystemCollector and SystemProvider.

Among many elements of the profile, <EventProvider> is the most used element and most configurable. The subjects covered in the previous posts can get us to start capturing the events we want using the default settings. However, there are always reasons that the default settings would not meet the requirements. Let us find out more about the optional attributes that can adjust the properties of the event providers.

EventProvider

<EventProvider> element in WPRP profile represents the configuration of the non-system ETW provider. Since there is only one system provider, everything else belongs to <EventProvider>. The simplest way to listen to a provider is to declare the provider and include the provider id in the <Profile> element as below. Refer to the simplest custom profile for the full xml.

<EventProvider Id="EventProvider_WPRC_TraceLogging" Name="B781B9CC-9BCC-486C-A036-D7BF98040A6B" />
…
<Profile Id=”WPrTest.Light.File” … >
  <Collectors>
    <EventCollectorId Value="EventCollector_WPR">
      <EventProviders>
        <EventProviderId Value="EventProvider_WPRC_TraceLogging"/>
      </EventProviders>
    </EventCollectorId>
  </Collectors>
</Profile>

EnabeTraceEx2 API

EnableTraceEx2 API is the public API to enable each event provider in a trace session one by one. Essentially, <EventProvider>’s child elements and attributes set the parameters of this function.

Required Attributes

As in the example above, the only thing you need to declare the provider is Id and Name attributes.

• Id – Unique string
• Name – the name of event provider

Id is a straightforward unique string to declare the provider. However, Name can be a little more complex. Depending on the type of the event provider, the Name can be one of value below.

• Manifested provider – The registered provider name or GUID
• WPP provider – GUID
• Tracelogging provider – GUID or star(*) + name of the provider, if no GUID exists.

To make it easy, I recommend using the descriptive unique string for the Id and GUID for the Name attributes.

Optional configurations – attributes and child elements

If you declare the event provider without any other optional attributes or child elements, WPR will give the default values to the optional configurations. This means, the keyword and level are set to the maximum possible value, and you will get all the events from the provider. The default setting maybe all you need but there is a lot more. You can listen to only certain keywords of event, certain level of the events such as warnings and beyond, collect the stacks for events, request the provider to log its state at certain time, and much more. In fact, EventProvider is the most configurable element in WPR profile schema. Let us find out how to use those commonly used optional configurations.

Common attributes

• Stack – when set to true, you can get the stackwalk event along with the provider’s events. Don’t forget to use it with <SystemCollector> with ProcessThread and Loader to resolve symbols.
• NonPagedMemory – indicates that the trace session uses non-paged memory. Though the attribute is for the provider, the property applies to the whole session. You must set this true if the provider is running in kernel such as the driver.
• Level – sets the maximum ETW logging verbosity level that you want the provider to write.
• CaptureStateOnly – used to indicate that the provider is not enabled for the entire tracing time, but only for the specified time such as during the start, save, or on-demand.
• Strict – indicates that the provider is critical, and trace does not start if the provider fails to be enabled, i.e., EnableTraceEx2 returns failure. Use this attribute to make sure the provider is enabled as configured.

Optional child Elements

• Keywords – 64-bit bitmask of keywords that restricts the events that you want the provider to write. If unused, the default value is 0xfffffffffffffffff. This value sets MatchAnyKeyword and MatchAllKeyword value with the same value.
• CaptureStateOnStart – requests the provider to log its state information when the trace starts, with the specified keyword value within this element. The ControlCode is set to EVENT_CONTROL_CODE_CAPTURE_STATE.
• CaptureStateOnSave – same as above, requests the provider when the trace stops.
• CaptureStateOnDemand – same as above, requests the provider when you execute ‘WPR -CaptureStateOnDemand’ command.

Examples

There are many examples of <EventProvider> used in the profile in MSDN doc.

Common Failure Codes

These are common error codes with regards to the <EventProvider> element.

Summary

WPR enables each event provider that is defined in <EventCollector> individually by using EnableTraceEx2 function. In this article, I explained about <EventProvider> elements and attributes that essentially set the parameters of EnableTraceEx2 function and common error codes. I left out some attributes and elements that are less common. Some of them are the event filtering elements. I hope to introduce them in the future.