Enterprise Instrumentation Framework

In previous sections, you explored three methods of instrumenting your application. Each method had both benefits and limitations. When employing any of those methods, you have to choose which one you think would work best and then code it into your application. In addition, you are forced to learn the different APIs for each method that you choose to deploy. Unfortunately, if you choose the wrong one, you would have to recode your instrumentation with your new choice. For most developers, this is a major drawback. Fortunately, Microsoft has provided this solution for you: the Enterprise Instrumentation Framework (EIF). Unfortunately, it is available only in the Visual Studio .NET Enterprise Architect edition.

Introducing the EIF

The Enterprise Instrumentation Framework is a simple yet extensible framework for instrumenting your application. It provides a unified API for instrumenting your application using the event log, WMI, or Windows Trace. More importantly, it enables you to tell the application at runtime, in a configuration file, which method to employ. As previously stated, this was a major drawback of using the individual method's API directly. By supporting the instrumentation of applications on one machine as well as applications that are distributed across multiple machines, the Enterprise Instrumentation Framework is suitable for all enterprise-class applications. Some important features of the Enterprise Instrumentation Framework are as follows:

• It provides a unified programming model that both enterprise developers and system developers alike can use.

• It uses a structured WMI event schema. This enables the development, test, and operations teams to work together to support the application.

• It implements a scriptable configuration layer. This enables the operations teams to configure how to raise or log events from an application.

• It supports raising or logging events through WMI, Windows event log, and Windows event tracing.

• It correlates events to business processes or operations using request tracing. This enables your operations staff to troubleshoot requests across a distributed application.

Enterprise Instrumentation Framework Requirements

Along with the benefits of using the Enterprise Instrumentation Framework come some limitations. These limitations come in the form of system requirements. Before embarking on the journey of using the EIF, make sure that your system meets the following requirements:

• The EIF is compatible with the .NET Framework 1.0 Service Pack 2 and above.

• Visual Studio .NET Enterprise Architect, Visual Studio .NET Enterprise Developer, or Visual Studio .NET Professional.

• Windows XP Professional or Windows 2000 Professional Service Pack 3 or later.

Elements of the EIF

The EIF uses a number of elements that interact together to support application instrumentation. As shown in Figure 44.12, there are five main elements of the EIF architecture.

• Event schema The event schema defines the set of events that an application can raise.

• Event sources The event sources are the objects that the applications use to raise events.

• Event sinks The event sinks are objects that represent event-reporting mechanisms.

• Instrumentation API The instrumentation API is a unified API for providing application instrumenting to an application.

• Configuration File The configuration file enables you to define which instrumentation to use and which events to filter out.

Event Schema

The event schema is similar to an interface in C#. It is a contract between the development and operations team that states which events an application can raise. Applications that use the EIF publish well-known events to which the operations team can observe and respond.

Event Sources

Although the enterprise instrumentation framework provides a default event source for each application, you can define additional event source objects. Event sources are the mechanism in the EIF to raise events. Using the configuration file, you can configure the event sources to determine which events are raised, the information they contain, and to which event sink (described in the next section) the events will be routed. The EIF supports two types of event sources: SoftwareElement and Request.

SoftwareElement Event Source

The SoftwareElement event source is a basic event source that provides simple events. They can be linked to classes, pages, or components in order to raise events.

The EIF creates a default SoftwareElement event source with the reserved name Application. If you do not specify an event source, the EIF assumes and assigns the default event source Application to the event. By enabling you to create many event sources, the EIF gives you greater flexibility in that it gives you the ability to filter out unwanted information assigned to different event sources.

Request Event Source

A Request event source provides events that include contextual information about an application or process. Closely linked to the business process of an application, the Request event source enables you to mark the beginning and end of a process such as a transaction or business logic.

For example, in an application that forces you to log on to the system before any additional functionality can be used, you can choose to use a Request event source to mark the beginning of the users attempt to log on, log the steps the user took such as entering the wrong password twice, and then mark the end of the process when the user finally enters the correct password. This enables the operations team to identify any problems that might occur when the user was attempting to log on to the system.

Event Sinks

An event sink represents the method of instrumentation, such as WMI, trace log, or event log. Event sinks are specified in your application's EIF configuration file (explained in a later section) and are not objects that you instantiate and use directly. The EIF enables you to use three standard event sinks: traceEventSink, LogEventSink, and WMIEventSink. In addition to these three standard event sinks, you can develop your own custom event sink. If you choose to create your own event sink, you can use an existing log format and routing mechanism such as MSMQ.

traceEventSink

The TRaceEventSink writes events to a Windows event trace log file. The location of the log file is determined by looking at the settings for the trace session named in the event sink. The TRaceEventSink is suitable for high frequency events. Although the tools for viewing the trace logs are limited, you can create a custom tool for reading and analyzing the trace logs by using the traceLogReader API.

LogEventSink

The LogEventSink writes events to the Windows event log. The default severity of the entry and the computer to which the entry is written are determined by the event sink parameters. Because the event log has a limited capacity of events that it can store, it is suitable only for low frequency events such as high level logging of an application.

WMIEventSink

The WMIEventSink sends the events to WMI. In addition, WMI supports the greatest number of management tools. These tools enable you to easily analyze the instrumentation data from your application. However, because WMI is somewhat performance-challenged, it should be used only for infrequent and high visibility events. Not withstanding the previous statement, the performance of WMI has been greatly improved and will likely be improved further in the future.

Request Tracing

Request tracing enables you to trace a business process through the course of its execution and is a key feature of EIF. Unlike any of the other tracing mechanisms, request tracing works between defined start and end points in your application's code. Any events that are raised between these points contain information that identifies them as being part of this request. Because the EIF implements request tracing using .NET's Remoting infrastructure, the LogicalCallContext class stores the information about the request. Unfortunately, there are three scenarios that do not currently support request tracing:

• Managed code calling into native code, which calls back into managed code

• Managed code sending an MSMQ message, triggering additional code on the listener

• Managed code invoking a SOAP web service, which then executes additional managed code

In each of these scenarios, the request does not include the execution path after the scenario.

Configuring EIF

The EIF configuration file enables you to define which instrumentation to use and which events to filter out in a production environment. Providing both configuration files and a configuration API, the EIF makes it possible for you to control event generation, tracing, and logging. In the EIF, there are two types of configuration files: application and Windows event trace session configuration files.

Application Configuration File

Every application that uses the Enterprise Instrumentation Framework has its own application configuration file. By default, the file is named Enterpriseinstrumentation.config. By using this file, you can configure event sources. This enables you to specify which instrumentation technique (WMI, event trace, or event log) and which events to allow or filter out. Although you specify most of the configuration information when you deploy the application, you can use this file to fine-tune the settings. The application configuration file enables you to define and control the following: event source registration and parameters, event sink configuration, event categories, event filters, and filter bindings.

Windows Event Trace Session Configuration File

The default Windows event trace session configuration file is named traceSessions.config. This file can be edited manually or through the API. Each trace session corresponds to a trace log file on your computer. This enables you to have different log files for each trace session.