System ETW Provider Configuration Settings
Updated: May 20, 2016
All PEF providers are instrumented with Event Tracing for Windows (ETW) technology so that Message Analyzer can leverage its infrastructure for data collection, session control, buffer configuration, and so on, as described in ETW Framework Tutorial. As a result, all PEF providers contain a core ETW Provider component that interacts with an enabling ETW Session where it writes events that Message Analyzer can capture. Other ETW Providers that are registered on your system were originally created by instrumenting various Windows components with ETW technology; as a result, they too can leverage the ETW infrastructure and Message Analyzer can capture their events. In this documentation, these are referred to as system ETW Providers, and in general, they write events from various applications and components on your system, such as Dynamic Host Configuration Protocol (DHCP), Domain Name System (DNS), Lightweight Directory Access Protocol (LDAP), and so on. These system ETW Providers are accessible from the Add Provider library on the ETW Providers toolbar that is located on the Live Trace tab of the New Session dialog.
Message Analyzer enables you to select specific data from a live trace by setting the low-level filtering configuration for events written by numerous system ETW Providers. The conceptual section that follows provides some background on event tracing to help clarify the meaning of these filtering features.
Not all system ETW Providers that you add to your Live Trace Session configuration from the Add Provider drop-down list have event Keyword and error Level filtering available. This simply means that when the manifest for the provider was created to instrument a particular Windows component with ETW technology, no Keyword or Level filtering configurations were specified by the developer. This usually means that the ETW Provider will deliver all events to an enabling session, or whatever events occur. If Keyword and Level configurations are available and you want to configure such filters, refer to the following sections to understand how to set and use them.
Event tracing is built upon an API that exposes the following ETW components:
ETW Session — provides an environment that accepts events, buffers them, and creates a trace file for logging the events or delivers them live in real-time to an ETW Consumer.
ETW Controller — enables providers, starts and stops event tracing sessions, defines log files, obtains execution statistics, sets the buffer configuration, and so on. Note that a provider is turned on only when it is enabled for an ETW Session by the ETW Controller.
ETW Provider — provides events to an event tracing session. A provider defines its interpretation of being enabled or disabled. In general, an enabled provider generates events, whereas a disabled provider does not.
ETW Consumer — consumes the events from an event tracing session.
When an ETW Controller enables an ETW Provider, it exposes the provider event configuration to the ETW Session to enhance the provider’s filtering instrumentation. An ETW Provider event configuration is specified with the use of the following two elements:
Level — a 1-byte integer that enables filtering based on the severity or verbosity of events.
Keywords — an 8-byte bitmask that enables the filtering of events from specific provider subcomponents.
For example, by selectively enabling these filtering features, the ETW Controller can enable providers to log the following:
Only the error events from a particular provider subcomponent.
All events from specific provider subcomponents.
Specific events from provider subcomponents.
When an ETW Controller enables a particular event Level, all provider events with a Level value that is less than or equal to what the Controller specified are also enabled.
Message Analyzer provides the following filtering settings for system ETW Providers that appear in the ETW Providers list on the Live Trace tab of the New Session dialog. The settings are accessible on the ETW Core tab of the Advanced Settings dialog that displays when you click the Configure link of a provider in the ETW Providers list:
KeywordToMask — not used.
Keywords(Any) — specifies a bitmask of keywords that determine the category of events a provider writes. The provider will write an event if the event's keyword bits match any of the bits set in this mask.
Keywords(All) — an optional mask that further restricts the category of events that a provider writes. If the keyword of an event meets the Keywords(Any) condition, the provider writes the event only if all bits in the Keywords(All) mask also exist in the event keyword configuration. This mask is not used if Keywords(Any) is set to zero.
To ensure that a provider writes all events, set the Keywords(Any) mask to zero (0x000000000000000). To include only specific events, set the Keywords(Any) mask to the keyword values of those events. For example, a provider might define events with specific keyword value settings as follows:
Provider Event Configuration:
Initialization event — sets keyword bit 0 (0x000000000000001).
File read operation — sets keyword bit 1 (0x000000000000002).
File write operation — sets keyword bit 2 (0x000000000000004).
In this configuration of provider events, if you wanted to receive initialization and file read operation events only, you would set the Keywords(Any) value in the ETW provider configuration to hexadecimal 0x000000000000003 (equal to 3 in decimal, 0011 in binary). However, a provider might have a more complex event keyword configuration such as the following:
Read Local Event Configuration:
File read operation—sets keyword bit 0.
Local access—sets keyword bit 1.
Read Remote Event Configuration:
File read operation—sets keyword bit 0.
Remote access—sets keyword bit 2.
In this case, you could set Keywords(Any) to 0x0000000000000001 to receive all read events local and remote, or you could set Keywords(Any) to 0x0000000000000001 and Keywords(All) to 0x0000000000000005 to receive only remote read events.
If an event's keyword is zero, the provider will write the event to the session regardless of the Keywords(Any) and Keywords(All) mask settings. The table that follows describes the Keyword filter settings that you can specify for system ETW Providers in Message Analyzer.
Setting the Error Level
For events that are delivered to an enabling ETW session, you can obtain an indication of the severity or verbosity of event errors by setting the error level that the session will report for the events of a particular ETW provider. To do this, select a particular value from the Level drop-down list on the ETW Core tab of the Advanced Settings dialog for a particular ETW provider. The values that you can set are described in the table that follows.
You may be able to discover event Keyword bitmasks and error Level settings for various trace providers on your system by following the procedure in Finding System ETW Provider Keywords.
Table 4. System ETW Provider Keyword and Level filter configuration
You can configure this setting to one of the following values:
Specifies the level of detail included in the ETW provider event. Levels indicated in the Values column to the left are inclusive. For example, if you set the Level to Verbose, the provider will write all Critical, Error, Warning, and Information events as well. If you set the Level to Warning, the provider will also write all Critical and Error events.
You can configure this setting in either of the following ways:
Provides a convenient way to add filtering at the kernel level, which enhances performance as follows:
You can configure a Keywords(Any) filter value by setting the hexadecimal keyword value that is displayed in the column to the right of the Keywords(Any) filter.
You can also access the configuration by clicking the ellipsis […] to the right of the hexadecimal keyword value, to display the ETW Keyword Filter Property dialog. From this dialog, you can select Manual to specify a keyword value, or you can select Automatic to choose a value based on a preset keyword filter property, which indicates a subcomponent of the provider.
You can configure this setting in either of the following ways:
Provides a convenient way to add filtering at the kernel level, which enhances performance as described above.
To configure a Keywords(All) filter value, you can set the hexadecimal keyword value that is displayed in the column to the right of the Keywords(All) filter.
Using this filter further restricts the events that will be written by the system ETW Provider. Only if an event keyword matches the Keywords(Any) condition and only if all bits in the Keywords(All) mask also exist in the event keyword configuration will the provider write the event/s.
In many cases, you will find predefined Keyword configurations in the ETW Keyword Filter Property dialog that displays when you click the ellipsis on the Keywords(Any) or Keywords(All) drop-downs that appear on the ETW Core tab of the Advanced Settings dialog for any particular ETW provider. However, you can also use Performance Monitor to view the configuration of certain system ETW Providers as they are running in live Windows Event Tracing Sessions. To view the event Keyword and error Level configuration for events that such providers write, follow the steps below.
From the Start menu or from the desktop, right-click Computer or the Computer icon, respectively, and select the Manage item to display the Computer Management console.
In the Computer Management (Local) pane, expand the Performance node, expand the Data Collector Sets node, and then click Event Trace Sessions.
The name and status of event trace sessions that are running on your machine are displayed.
Right-click an event trace session such as EventLog-System and select the Properties item from the menu.
The EventLog-System Properties dialog displays.
Select the Trace Providers tab and then select a provider in the Providers list box.
The current Keyword and Level configuration of the provider you selected displays in the Properties list box.
In the EventLog-System Properties dialog, click the Edit button to display a list of all the Keywords that define the events that the selected provider can write to a trace consumer, which are typically specified in the provider manifest.