Developing Using Event Reporting and Tracing

Developing using Event Reporting and Tracing

Windows Vista® contains two facilities for event reporting and tracing:

• Event Tracing for Windows (ETW)

  Present since Windows 2000, this high-performance technology enables the instrumentation and monitoring of applications, typically during optimization, debugging, and performance tuning. Because of its high-performance design, it has limited querying, subscription, and forwarding capabilities.

• Windows Event Log

  New with Windows Vista, it is used to create, publish, receive, and store system and application events for the primary purposes of diagnostics and auditing.

The Windows Event Log service has an associated API that, in conjunction with the ETW API, unifies much of this functionality for the developer. This API is targeted at the C/C++ programmer. For more information about the Windows Event Logging API, see "Windows Event Log" in the Windows SDK. (The section entitled "Event Logging" covers the older NT Event Log API.)

Architecture and Concepts

Logging events are operating system, service, application, or hardware/device driver occurrences that convey important information about performance, critical events, errors, warnings, security operations, and completion of operations. Events are defined by publishing applications in an instrumentation manifest file that uses the XML-based EventManifest Schema. During runtime, events are objects that are accessed through handles of type EVT_HANDLE. These objects have a numeric identification code, associated attributes, and operation-specific data represented in binary or the XML-based Event Schema. Events are often persisted in log files by using the Event Schema. Both XML schemas are fully defined in the "Windows Event Log Reference" in the Windows SDK.

Events, represented using the XML-based Event Schema, are published into event channels, which represent a pipeline that connects event publishers (sources) to event consumers, including log files. Windows Event Log's unified architecture is largely accomplished through the consistent use of channels. The Windows Event Log service defines a hierarchy of channel namespaces as shown in the following diagram:

Global channels are public channels that may be shared by multiple publishers and consumers, including the operating system. These channels map directly to the standard system logs in Windows. Their lifetime is controlled by Windows or the system administrator. Application channels are typically created, managed and used by a single application. Each application can define one or more private channels, although two are common:

• The standard Operational channel typically contains events about installation, configuration or lifecycle changes within the application.

• The Diagnostic channel typically contains ETW tracing information for that application.

There is a log file associated with every channel and both are secured through standard system ACL-based read/write/clear security tokens. Each channel can have an associated filter that determines which messages are stored to the associated log file. By default, log files are stored in the directory:

<%windows%>\system32\winevt\logs\<channel-name>.<log-format-extension>

Event publisher and channel properties are initially specified in an instrumentation manifest, but can be dynamically read and modified through Event Log functions.

Applications can access events in one of two standard ways:

• As subscribers, applications can receive notice of either past events or live events as they occur by subscribing to event notifications. Subscribers can either use an asynchronous push programming model or a synchronous pull model to receive notifications.

• As event log readers, applications can read past event data from a log file. Compatible sources include the following file formats: older NT Event Log (.evt) files, archived events logs (.elf, .csv, or .txt), Event Tracing for Windows log files whose contents are described by Managed Object Format (MOF), and Windows software trace processor (WPP) files (.etl). (WPP is used primarily when developing kernel-mode device drivers.)The EvtExportLog function supports exporting from legacy log files as well as from channels. The Event Viewer (EventVwr.exe) is an example of an event log reader.

After a source is selected, events can be queried and filtered in uniform ways, primarily by using XPath 1.0 expressions in Event Log functions such as EvtQuery. This API also has functions for clearing, exporting, and archiving previously logged events.

Compatibility and Managed Support

The Windows Event Log service and APIs are only available starting with Windows Vista. Older NT Event Log APIs are supported, but these calls are actually mapped to the new Windows Event Log Service.

Applications using this older API store their event message information in a separate message text file that is not directly usable by the Windows Event Log API. To migrate these applications, developers must convert the message text files into usable form using one of the following techniques:

• The Mc2Man migration toll, which can generate a single instrumentation manifest from one or more, older MC text files

• The Message Compiler (MC.exe), which can compile message text files into a binary resource that then is added to the project's resource file

The .NET Framework library supports logging through the System.Diagnostics namespace, through classes such as EventLog, EventLogEntry, and EventLogInstaller. These classes are implemented to use the native ETW and NT Event Log APIs. However, because Vista routes the latter API to the new Windows Event Log service, the managed logging classes are effectively updated.

Windows Event Collector

The Windows Event Log contains a subsystem, the Windows Event Collector, which manages event subscriptions on the local machine. There is also an associated API for applications and tools that need to enumerate existing subscriptions, get or set the properties of the subscriptions or their associated event sources, or create new or delete existing subscriptions. For more information, see "Windows Event Collector Reference" in the Windows SDK.

Publishing and Consuming Events

The Windows Event Log API and tools enable developers to create powerful event publishers and consumers. Developing and testing a publisher is considerably more difficult to do, and an ill-behaving publisher can negatively impact the logging subsystem. The relationship between the event publisher, consumer, log files, and the Windows Event Log components is shown in the following diagram:

Publishing Events

The following steps are used to develop a user-mode event publishing application.

1. The application must be logically analyzed so that the entire range of required events is specified. Categorize events into standard types (for example, administrative, operational and analytic, debug, and tracing) and custom categories. A holistic analysis should include user requirements, lifecycle, and health modeling of the application. Privacy and security issues concerning event messages and their contents should be considered at this stage.

2. Create an instrumentation manifest for the application that contains publisher metadata, event definitions and templates, channel definitions, and the localized event messages. The manifest is an XML-based document that uses the EventManifest Schema. It is easiest to start with an existing XML template or example manifest. The schemas used by the Windows Event Log API are fully documented in the "Windows Event Log Reference" section of the Windows SDK.

3. Build the manifest with the Message Compiler (MC.exe) tool, which generates a header file and binary resources (messages and event templates). Next, include these files into the applications project: add the binary resources to the project's resource (.rc) file, and add the header file to the list of project files.

4. Add source code to publish events at appropriate occasions in the application by using the EWT and Windows Event Log APIs (for example, by using the EventWrite function).

5. Build and debug the application.

6. If the events are to be consumed on a remote machine, then the publisher manifest must be deployed to that machine using the Wevtutil.exe command-line tool.

For more information, see "Developing Event Publishers" in the Windows SDK.

Consuming Events

Applications can consume events for a variety of purposes and use different mechanisms to access event information using the Windows Event Log API. The most common client operations include querying for, subscribing to, and formatting events.

• The EvtQuery function is used to query live log events and log files. It takes XPath expressions to filter events. With either source, if this function is successful, it returns an EVT_HANDLE object that represents the resultant event collection.

• An application can subscribe to events using the EvtSubscribe function. This function supports both push and pull subscription models. (In the push model, the application provides a callback function; using pull, the application calls the EvtNext function to obtain the next event.) Using either, the application receives an EVT_HANDLE object that represents the event.

• Event result sets can be stepped through with the EvtNext function, or use EvtSeek to jump to a certain location in the set.

• Events can be formatted as XML using the EvtRender function.

For more information about consuming events, see "Using Windows Event Log" in the Windows SDK.

Windows Event Log Tools

Windows Vista and the Windows SDK provide a number of tools that are essential when working with or developing for Windows Log Events.

Tool	Description
Event Viewer (EventVwr.exe)	Windows Vista contains an updated MMC snap-in that lets you browse, query and manage event logs. It also enables the user to schedule a task to run in response to an event.
Event Utility Command Tool (WevtUtil.exe)	Manages channel subscriptions, publisher configurations, event logs and instrumentation manifests.
Message Compiler (MC.exe)	Compiles instrumentation manifests and message text files into binary format files that can be added to a project's resource file.
Mc2Man.exe	This command-line migration tool generates a single instrumentation manifest from one or more, older MC text files.