How to Enable WPP Tracing Through the Windows Event Log Service

The Windows Event Log service supports WPP logging and decoding. This topic describes how to enable WPP tracing through the Windows Event Log service.

Enabling WPP tracing in this scenario requires no extra work to the WPP provider. However, to use the Windows Event Log service, you must supply a manifest and an Event Log provider. To enable WPP tracing, declare a debug channel and specify the associated control GUID as declared for your WPP provider.

WPP tracing is not meant to be enabled all the time, so by default the enable attribute in the manifest should be set to false. When WPP tracing is needed, change the attribute in the manifest, so that enabled=»true».

You cannot specify or individually select control bits. To enable all WPP events to this channel, specify a keyword value of 0XFFFFFFFF. Internally, control bits map to keywords; if you know which bit maps to a specific keyword, you can select that keyword to get a specific set of events. In the example manifest, the keyword value is 0xFFFF because less than 16 WPP control bits are needed. To get a specific set of events after installation, you may change the keywords using the wevtutil.exe command-line utility. The command is:

wevtutil sl /k:

Note that the channel must first be disabled to change the keyword value.

Declaring a channel in this manner enables both the WPP provider (whose control GUID is specified) and the Event Log provider (under which this channel is declared) to access the debug channel, so either provider can write to this channel. WPP events or normal ETW events can now be seen under this channel through the event viewer.

About Event Tracing

Event Tracing for Windows (ETW) is an efficient kernel-level tracing facility that lets you log kernel or application-defined events to a log file. You can consume the events in real time or from a log file and use them to debug an application or to determine where performance issues are occurring in the application.

ETW lets you enable or disable event tracing dynamically, allowing you to perform detailed tracing in a production environment without requiring computer or application restarts.

The Event Tracing API is broken into three distinct components:

• Controllers, which start and stop an event tracing session and enable providers
• Providers, which provide the events
• Consumers, which consume the events

The following diagram shows the event tracing model.

Controllers

Controllers are applications that define the size and location of the log file, start and stop event tracing sessions, enable providers so they can log events to the session, manage the size of the buffer pool, and obtain execution statistics for sessions. Session statistics include the number of buffers used, the number of buffers delivered, and the number of events and buffers lost.

Providers

Providers are applications that contain event tracing instrumentation. After a provider registers itself, a controller can then enable or disable event tracing in the provider. The provider defines its interpretation of being enabled or disabled. Generally, an enabled provider generates events, while a disabled provider does not. This lets you add event tracing to your application without requiring that it generate events all the time.

Although the ETW model separates the controller and provider into separate applications, an application can include both components.

For more information, see Providing Events.

Types of Providers

There are four main types of providers: MOF (classic) providers, WPP providers, manifest-based providers, and TraceLogging providers. You should use a manifest-based provider or a TraceLogging provider if you are writing applications for WindowsВ Vista or later that do not need to support legacy systems.

MOF (classic) providers:

• Use the RegisterTraceGuids and TraceEvent functions to register and write events.
• Use MOF classes to define events so that consumers know how to consume them.
• Can be enabled by only one trace session at a time.

WPP providers:

• Use the RegisterTraceGuids and TraceEvent functions to register and write events.
• Have associated TMF files (compiled into a binary’s .pdb) containing decoding information inferred from the preprocessor’s scan of WPP instrumentation in source code.
• Can be enabled by only one trace session at a time.

Manifest-based providers:

• Use EventRegister and EventWrite to register and write events.
• Use a manifest to define events so that consumers know how to consume them.
• Can be enabled by up to eight trace sessions simultaneously.

TraceLogging providers:

• Use TraceLoggingRegister and TraceLoggingWrite to register and write events.
• Use self-describing events so that the events themselves contain all required information for consuming them.
• Can be enabled by up to eight trace sessions simultaneously.

All event providers fundamentally use the Event Tracing family of APIs (TraceEvent for legacy technologies and EventWrite/EventWriteEx for newer ones). Event providers simply differ in what field types they store in event payloads and where they store the associated event decoding information.

Consumers

Consumers are applications that select one or more event tracing sessions as a source of events. A consumer can request events from multiple event tracing sessions simultaneously; the system delivers the events in chronological order. Consumers can receive events stored in log files, or from sessions that deliver events in real time. When processing events, a consumer can specify start and end times, and only events that occur in the specified time frame will be delivered.

For more information, see Consuming Events.

Missing Events

Perfmon, System Diagnostics, and other system tools may report on missing events in the Event Log and indicate that the settings for Event Tracing for Windows (ETW) may not be optimal. Events can be lost for a number of reasons:

The total event size is greater than 64K. This includes the ETW header plus the data or payload. A user has no control over these missing events since the event size is configured by the application.

The ETW buffer size is smaller than the total event size. A user has no control over these missing events since the event size is configured by the application logging the events.

For real-time logging, the real-time consumer is not consuming events fast enough or is not present altogether and then the backing file is filling up. This can result if the Event Log service is stopped and started when events are being logged. A user has no control over these missing events.

When logging to a file, the disk is too slow to keep up with the logging rate.

For any of these reasons, please report these problems to the provider of the application or service that is generating the events. These issues can only be fixed by the application developer or the service logging the events. If the missing events are being reported in the Event Log Service, this may indicate a problem with the configuration of the Event Log service. The user may have some limited ability to increase the maximum disk space to be used by the Event Log Service which may reduce the number of missing events.

EVENT_TRACE_LOGFILEA structure (evntrace.h)

The EVENT_TRACE_LOGFILE structure specifies how the consumer wants to read events (from a log file or in real-time) and the callbacks that will receive the events.

When ETW flushes a buffer, this structure contains information about the event tracing session and the buffer that ETW flushed.

Syntax

Members

Name of the log file used by the event tracing session. Specify a value for this member if you are consuming from a log file.

This member must be NULL if LoggerName is specified.

You must know the log file name the controller specified. If the controller logged events to a private session (the controller set the LogFileMode member of EVENT_TRACE_PROPERTIES to EVENT_TRACE_PRIVATE_LOGGER_MODE), the file name must include the process identifier that ETW appended to the log file name. For example, if the controller named the log file xyz.etl and the process identifier is 123, ETW uses xyz.etl_123 as the file name.

If the controller set the LogFileMode member of EVENT_TRACE_PROPERTIES to EVENT_TRACE_FILE_MODE_NEWFILE, the log file name must include the sequential serial number used to create each new log file.

The user consuming the events must have permissions to read the file.

Name of the event tracing session. Specify a value for this member if you want to consume events in real time. This member must be NULL if LogFileName is specified.

You can only consume events in real time if the controller set the LogFileMode member of EVENT_TRACE_PROPERTIES to EVENT_TRACE_REAL_TIME_MODE.

Only users with administrative privileges, users in the Performance Log Users group, and applications running as LocalSystem, LocalService, NetworkService can consume events in real time. To grant a restricted user the ability to consume events in real time, add them to the Performance Log Users group or call EventAccessControl.

WindowsВ XP and WindowsВ 2000:В В Anyone can consume real time events.

On output, the current time, in 100-nanosecond intervals since midnight, January 1, 1601.

On output, the number of buffers processed.

Reserved. Do not use.

Modes for processing events. The modes are defined in the Evntcons.h header file. You can specify one or more of the following modes:

Value	Meaning
PROCESS_TRACE_MODE_EVENT_RECORD	Specify this mode if you want to receive events in the new EVENT_RECORD format. To receive events in the new format you must specify a callback in the EventRecordCallback member. If you do not specify this mode, you receive events in the old format through the callback specified in the EventCallback member. Prior to WindowsВ Vista:В В Not supported.
PROCESS_TRACE_MODE_RAW_TIMESTAMP	Specify this mode if you do not want the time stamp value in the TimeStamp member of EVENT_HEADER and EVENT_TRACE_HEADER converted to system time (leaves the time stamp value in the resolution that the controller specified in the Wnode.ClientContext member of EVENT_TRACE_PROPERTIES). Prior to WindowsВ Vista:В В Not supported.
PROCESS_TRACE_MODE_REAL_TIME	Specify this mode to receive events in real time (you must specify this mode if LoggerName is not NULL).

On output, an EVENT_TRACE structure that contains the last event processed.

On output, a TRACE_LOGFILE_HEADER structure that contains general information about the session and the computer on which the session ran.

Pointer to the BufferCallback function that receives buffer-related statistics for each buffer ETW flushes. ETW calls this callback after it delivers all the events in the buffer. This callback is optional.

On output, contains the size of each buffer, in bytes.

On output, contains the number of bytes in the buffer that contain valid information.

Pointer to the EventCallback function that ETW calls for each event in the buffer.

Specify this callback if you are consuming events from a provider that used one of the TraceEvent functions to log events.

Pointer to the EventRecordCallback function that ETW calls for each event in the buffer.

Specify this callback if you are consuming events from a provider that used one of the EventWrite functions to log events.

Prior to WindowsВ Vista:В В Not supported.

On output, if this member is TRUE, the event tracing session is the NT Kernel Logger. Otherwise, it is another event tracing session.

Context data that a consumer can specify when calling OpenTrace. If the consumer uses EventRecordCallback to consume events, ETW sets the UserContext member of the EVENT_RECORD structure to this value.

Prior to WindowsВ Vista:В В Not supported.

Remarks

Be sure to initialize the memory for this structure to zero before setting any members.

Consumers pass this structure to the OpenTrace function.

When ETW flushes a buffer, it passes the structure to the consumer’s BufferCallback function.

The evntrace.h header defines EVENT_TRACE_LOGFILE as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Event Logging (Windows Installer)

Windows Events provides a standard, centralized way for applications (and the operating system) to record important software and hardware events. The event-logging service stores events from various sources in a single collection called an event log. Prior to WindowsВ Vista, you would use either Event Tracing for Windows (ETW) or Event Logging to log events. WindowsВ Vista introduced a new eventing model that unifies both ETW and the Windows Event Log API.

The installer also writes entries into the event log. These record events such as following:

• Success or failure of the installation; removal or repair of a product.
• Errors that occur during product configuration.
• Detection of corrupted configuration data.

If a large amount of information is written, the Event Log file can become full and the installer displays the message, «The Application log file is full.»

The installer may write the following entries in the event log. All event log messages have a unique event ID. All general errors authored in the Error table that are returned for an installation that fails are logged in the Application Event Log with a message ID equal to the Error + 10,000. For example, the error number in the Error table for an installation completed successfully is 1707. The successful installation is logged in the Application Event Log with a message ID of 11707 (1707 + 10,000).

For information about how to enable verbose logging on a user’s computer when troubleshooting deployment, see Windows Installer Best Practices.