Export (0) Print
Expand All

System ETW Provider Configuration Settings

All PEF providers are instrumented with 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.

Important  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 configurations were specified by the developer. 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.

Conceptual Background

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.

Note  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.

System ETW Provider Keyword Filtering in Message Analyzer

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.

Note  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 filtering Level and Keyword settings that are available for the configuration of system ETW Providers in Message Analyzer.

Note  Keyword bitmasks and Level settings for various trace providers on your system can be discovered by following the procedure in Finding System ETW Provider Keywords.

Table 4. System ETW Provider configuration

Configuration Setting Values Description

Level

You can configure this setting to one of the following values:

  • Critical (1)

  • Error (2)

  • Warning (3)

  • Information (4)

  • Verbose (5)

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.

KeywordToMask

Not used.

Not used.

Keywords(Any)

You can configure this setting in either of the following ways:

  • Manual — you can manually set the value of an 8-byte integer to enable the system ETW Provider to write events that match the specified keyword values.

  • Automatic — you can select one or more preset keywords to automatically configure an 8-byte integer to enable the system ETW Provider to write events that match the specified keyword values.

Provides a convenient way to add filtering at the kernel level, which enhances performance as follows:

  • The provider selects specific data to retrieve, thereby reducing the number of messages being captured, which subsequently increases the speed at which data is captured.

  • Filtering at kernel mode level is inherently faster than user mode filtering.

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.

Note  Before setting this value, you should be familiar with the Keyword settings of the provider event you are trying to receive. You might need to consult the system ETW Provider manifest to obtain this information.

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.

Note  Not all system ETW Providers contain preset Keyword filter properties that are selectable from the ETW Keyword Filter Property dialog.

Keywords(All)

You can configure this setting in either of the following ways:

  1. Manual — you can manually set the value of an 8-byte integer to enable system ETW Provider events that contain all of the specified keywords.

  2. Automatic — you can select one or more preset keywords to automatically configure an 8-byte integer to enable system ETW Provider events that contain all of the specified keywords.

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.

Finding System ETW Provider Keywords


If you want to view the configuration of Windows system ETW Providers as they are running in Windows event tracing sessions, including the Keyword and Level configuration for events that they write, follow the steps below.

  1. 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.

  2. 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.

  3. Right-click an event trace session such as EventLog-System and select the Properties item from the menu.

    The EventLog-System Properties dialog displays.

  4. Select the Trace Providers tab and then select a provider in the Providers list box.

    The Keywords and Level configuration of the provider you selected displays in the Properties list box.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft