How To: Use EIF

Article
07/14/2010

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Improving .NET Application Performance and Scalability

J.D. Meier, Srinath Vasireddy, Ashish Babbar, and Alex Mackman
Microsoft Corporation

May 2004

Related Links

Home Page for Improving .NET Application Performance and Scalability

Send feedback to Scale@microsoft.com

patterns & practices Library

Summary: This How To shows you how to use the Enterprise Instrumentation Framework (EIF) to instrument Microsoft® .NET applications for improved manageability.

Applies To
Microsoft Visual Studio® .NET 2002 with the .NET Framework 1.0 SP2 or later

Microsoft Visual Studio® .NET 2003 with the .NET Framework 1.1

Overview
What You Must Know
Instrument an Application
Step 1. Create a Simple Console Application
Step 2. Add References to the Required Assemblies
Step 3. Add using Statements
Step 4. Add an Empty Installer Class
Step 5. Add Code to Raise Events Using the Application Event Source
Step 6. Add Code to Raise Events Using a SoftwareElement Event Source
Step 7. Compile the Application
Step 8. Enable Tracing in TraceSessions.config
Step 9. Run InstallUtil.exe Against Your Project
Step 10. Bind Events to Event Sinks
View the Logs
Issues with ASP.NET Applications
Additional Resources

Overview

The Microsoft Enterprise Instrumentation Framework (EIF) enables you to instrument .NET applications to provide better manageability in a production environment. EIF is the recommended approach for instrumenting .NET applications. It provides a unified API for instrumentation that uses the existing eventing, logging, and tracing mechanisms built into the Microsoft Windows® operating system, such as Windows Event Log, Windows Trace Log, and Windows Management Instrumentation (WMI). Members of an operations team can use existing monitoring tools to diagnose application health, faults, and other conditions.

An application instrumented with EIF can provide extensive information such as errors, warnings, audits, diagnostic events, and business-specific events. This you how to instrument your application by using EIF.

What You Must Know

EIF is installed to C:\Program Files\Microsoft Enterprise Instrumentation\ and starts a Windows service named Windows Trace Session Manager*.* Documentation is available in EnterpriseInstrumentation.chm in the Docs subfolder.

Event Sinks

The default provides three event sinks:

WMI. This event sink is the slowest of the standard eventing mechanisms on Windows 2000 systems; therefore, you should only use it for events that occur infrequently or high-visibility events.
Windows Event Trace. This event sink is suitable for higher-frequency eventing; for example, where your application generates hundreds or even thousands of events per second.
WindowsEvent Log. This event sink is suitable for lower-frequency events, such as errors, warnings, or high-level audit messages.

Event Sources

EIF events are always raised from a specific event source. The configuration of that event source determines whether the event is raised or not, what information the event contains, and to which eventing, tracing, or logging mechanism the event is routed.

EIF supports the following event sources:

SoftwareElement event source. You define and use a SoftwareElement event source to allow members of your operation team to control instrumentation behavior at a granular level. For example, individual classes or pages can use pecific SoftwareElement event sources.
Application event source. Event sources that are raised without specifying an explicit event source use the Application event source. This event source is created and managed automatically and is simple to use. Use it where individual control over a specific software element is not required. This option is particularly suited for most lower-frequency management events, such as notifications and errors.
Request event source. Request tracing is a key feature of EIF that allows you to trace business processes by following an execution path through a distributed application. In contrast to tracing a specific class or component, request tracing works between defined start and end points in the application's code. Any events raised along this execution path include information that identifies them as being part of that defined execution path or request. The Request event source inherits much of its functionality from the SoftwareElement event source.

Downloading and Installing EIF

EIF is distributed as a free download from Microsoft Download Center.

To download EIF

Download two files, ReadMe.htm and EnterpriseInstrumentation.exe, from the Microsoft Download Center at https://www.microsoft.com/downloads/details.aspx?FamilyId=80DF04BC-267D-4919-8BB4-1F84B7EB1368&displaylang=en.

To install EIF

Read ReadMe.htm for installation instructions and known issues.
Double-click EnterpriseInstrumentation.exe to install EIF.
In the Enterprise Instrumentation Setup Wizard, install EIF by selecting the default options.

Instrument an Application

The standard event schema includes events for errors, audits, administrative events, and diagnostic trace events. These can be raised from two event sources:

An application or software element
A request

To instrument an application, open the application source and then perform the following actions:

Create a simple console application.
Add references to the required assemblies.
Add using statements.
Add an empty installer class.
Add code to raise events using the Application event source.
Add code to raise events using a SoftwareElement event source
Compile the application.
Enable tracing in TraceSessions.config.
Run InstallUtil.exe against your project.
Bind events to event sinks.

Step 1. Create a Simple Console Application

Create a new C# console application, and add a simple class as shown in the following code.

using System;
namespace Client
{
  class Class1
  {
    [STAThread]
    static void Main(string[] args)
    {
      Console.WriteLine("Hello");
    }
  }
}

Step 2. Add References to the Required Assemblies

In this step, you add references to the required EIF assemblies.

To add references from Visual Studio .NET

In Solution Explorer, right-click the References folder, and then click Add Reference.
Select the following components:
- Microsoft.EnterpriseInstrumentation.dll
- Microsoft.EnterpriseInstrumentation.Schema.dll
- System.Configuration.Install.dll
Click Select, and then click OK.

**Note **If you are using the command-line tools, you will add the references during compilation in Step 7.

Step 3. Add using Statements

Add the following using directives to the top of Class1.cs.

using System.ComponentModel; // Required by the RunInstaller attribute
using Microsoft.EnterpriseInstrumentation;
using Microsoft.EnterpriseInstrumentation.Schema;
using Microsoft.EnterpriseInstrumentation.RequestTracing;

Step 4. Add an Empty Installer Class

At the top of the Client namespace, add an empty class that inherits from ProjectInstaller. Decorate the class with the RunInstaller attribute as follows.

[RunInstaller(true)]
public class MyProjectInstaller : ProjectInstaller {}

The installer class is instantiated by the InstallUtil.exe utility. The installer class creates the application's instrumentation configuration file, EnterpriseInstrumentation.config, which, among other things, controls how instrumentation events are routed to event sinks.

**Note **If your application has multiple classes, for example, an ASP.NET application with multiple Web Forms, you must only perform this step in one of the Web Forms. If you duplicate the class in each of your Web Forms, you will get a compilation error.

Step 5. Add Code to Raise Events Using the Application Event Source

Add the following lines of code to your application's Main method.

TraceMessageEvent.Raise("This is a trace event.");
ErrorMessageEvent.Raise("This is an error event.", 1, "CODE");
AuditMessageEvent.Raise("This is an audit event.");
AdminMessageEvent.Raise("This is an admin event.");

You can call the Raise method of the appropriate object anywhere in your application, whenever you want to raise a trace, error, audit, or administration event. Note that the error event has a message, severity, and error code.

Enterprise Instrumentation implicitly defines and manages an event source for the entire application. By using the Raise methods on the classes shown in the previous code fragment, you use the Application event source.

Because you do not need to define or reference an event source explicitly when raising events, this option provides the simplest programming model.

Step 6. Add Code to Raise Events Using a SoftwareElement Event Source

With this approach, each class has its own event source definition, so this option is appropriate for classes or pages that require a specialized eventing configuration.

To raise events using a SoftwareElement event source

Add the following static instance of an event source inside your Class1 class.
```
public static EventSource es = new EventSource("MyComponent");
```

Add the following code to the Main method to raise an event using the new event source.

// raise an event using the new event source
TraceMessageEvent.Raise(es, "Using a new event source");

For Request Tracing Event Sources Only

You can also enable request tracing to trace a specific business process such as credit card validation or order processing. To do so, you must first declare a RequestEventSource object and identify the object by using the name of the request that you want to trace. For example:

private static RequestEventSource TracedRequestEventSource = 
            new RequestEventSource("PlaceOrder");

Then you must add the following code around the request that you want to trace, which may be made up of multiple method calls.

using (RequestTrace request = new RequestTrace(TracedRequestEventSource))
{
  // Business logic and Method calls that are part of the request
  ...
} // request.Dispose is called here which completes the request trace

Any events raised by methods inside the using block that defines the scope of the request trace include information that identifies them as being part of that defined execution path, or request.

**Note **Instead of the C# using statement, you could use a try/finally block (or in Visual Basic® .NET, a Try/Finally block) and explicitly call request.Dispose in the finally block to ensure that the request trace completes.

Step 7. Compile the Application

If you are using Visual Studio .NET, on the Build menu, click Build Solution. If you are using the command-line tools, use a compilation statement similar to the following. Note that these instructions assume that your class file is named MyApp.cs.

csc.exe /out:MyApp.exe /t:exe /r:system.dll;
"C:\Program Files\Microsoft Enterprise Instrumentation\Bin\
Microsoft.EnterpriseInstrumentation.dll";
"C:\Program Files\Microsoft Enterprise Instrumentation\Bin\
Microsoft.EnterpriseInstrumentation.Schema.dll";
System.Configuration.Install.dll MyApp.cs

**Note **Enter this code as a single command line.

Step 8. Enable Tracing in TraceSessions.config

The TraceSessions.config file is located in the <EIF installation folder>\Bin\Trace Service folder. By default, the EIF installation folder is C:\Program Files\Microsoft Enterprise Instrumentation.

Edit the TraceSessions.config file and change the enabled attribute of the <session> element to "true" as shown in the following fragment.

<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns="http://.../TraceSessions.xsd">
  <defaultParameters ... />
  <sessionList>
    <session name="TraceSession" enabled="true" fileName="..." />
  </sessionList>
</configuration>

Step 9. Run InstallUtil.exe Against Your Project

Run the Visual Studio .NET Command Prompt as a user who has Administrator permissions. Access the folder in which your project's compiled executable file is located. Run InstallUtil.exe from the command line with your project's compiled executable file and any supporting components as parameters.

Run InstallUtil.exe against your project. For example:

C>:\YourProject\bin\Debug>installutil.exe myproj.exe

Running this utility against your project creates an EnterpriseInstrumentation.config file in your application's output folder. For example, for a debug build:

C>:\YourProject\bin\Debug\EnterpriseInstrumentation.config

**Note **InstallUtil.exe is included with the .NET Framework. For more information about InstallUtil.exe command-line arguments, see "Installer Tool (InstallUtil.exe)," in the .NET Framework SDK documentation.

When Installutil.exe is finished running, you should see the following lines of output at the command prompt.

The Commit phase completed successfully.
The transacted install has completed.

**Note **If you get an error, see the "Internal Error and Informational Events" topic in the EIF documentation.

Step 10. Bind Events to Event Sinks

By changing the EnterpriseInstrumentation.config file, you can bind events generated by various event sources to various event sinks, including WMI, Windows Trace Log, or the Windows Event Log.

To edit EnterpriseInstrumentation.config

Open EnterpriseInstrumentation.config in your project's output folder.

Locate the following <filter> element.

<filter name="defaultSoftwareElementFilter" 
    description="A default filter for the Software Element event sources." />

Replace the element you located with the following elements.
```
<filter name="defaultSoftwareElementFilter" 
  description=" A default filter for the Software Element event sources.">
   <eventCategoryRef name="All Events">
       <eventSinkRef name="wmiSink" />
       <eventSinkRef name="traceSink" />
       <eventSinkRef name="logSink" />
   </eventCategoryRef>
</filter>
```
Notice that in this fragment, an <eventCategoryRef> element has been added as a child of the <filter> element, with one <eventSinkRef> element for each of the sinks that you want events routed to. The fragment routes application and software element events to WMI, Windows Event Log, and Windows Trace Log.

**Note **You can comment out lines in EnterpriseInstrumentation.config using the standard comment tags, . For example,

View the Logs

Run your console application to generate various event messages and then view the log output as described here.

Windows Trace Log

To view output in the Windows Trace Log, start the Trace Viewer sample application located in the Trace Viewer folder.

To view the Windows Trace Log

Start the TraceView.exe application, which is located in the following folder.

C:\Program Files\Microsoft Enterprise Instrumentation\Samples\Trace Viewer\TraceViewer.exe

On the File menu, click Open and open the following file.

C:\Program Files\Microsoft Enterprise Instrumentation\Bin\Trace Service\Logs\TraceLog.log

On the View menu, click Add/RemoveColumns.
Select MachineName and Message and click Add.
Click OK. You will see the additional columns.

An alternative approach is to use the trace log reader sample located in the Trace Log Reader folder beneath the Samples folder.

Important Attributes of an Event

Table 1 shows some of the important values that can be retrieved from each event.

Table 1: Sample Event Attributes

Value	Description
Message	A custom string you can supply when the event is fired.
ProcessName	The application generating the event. This will be the ASP.NET process if the event is fired from an ASP.NET application or Web service.
EventSourceName	This is "Application" by default, but you can set it to a named component to group events.
EventSequenceNumber and RequestSequenceNumber	Use these numbers to determine the order in which events occurred. Use these values instead of TimeStamp.
TimeStamp	When the event occurred. Use EventSequenceNumber and RequestSequenceNumber to order events.
RootRequestName and RequestName	A named request, for example, NorthwindSite.Order.Create. The two names are different only if there are nested requests.

Windows Event Log

To view the contents of the Windows Event Log, use the Event Viewer program (Eventvwr.exe) located in the Administrative Tools folder.

To view the Windows Event Log

On the Start menu, click Run.
Type Eventvwr.exe and click OK.
In the left pane, click Application.
On the View menu, click Filter.
Change the Event source to Application (MyApp), and then click OK. The event messages that use the Application event source will be displayed.
On the View menu, click Filter and change the Eventsource to MyComponent and then click OK. The event message that uses the MyComponent event source will be displayed.

WMI

To view WMI events, install the WMI SDK, which is available for free download at https://www.microsoft.com/msdownloa/platformsdk/sdkupdate/.

Sample Output from Instrumentation

A typical instrumentation event output will look like the following example, regardless of the mechanism used to view the event.

Microsoft.EnterpriseInstrumentation.Schema.TraceMessageEvent{   String Message = "Creating customer: begin"   Int32 ProcessID = 3620   String ProcessName = "C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\aspnet_wp.exe"   String ThreadName = ""   ComPlusInfo ComPlus = <null>   WindowsSecurityInfo WindowsSecurity = <null>   ManagedSecurityInfo ManagedSecurity = <null>   String StackTrace = ""   String EventSourceInstance = "aab5cf6c-dbbd-45c9-ae4f-3d989a90902e"   String EventSourceName = "Application"   Int64 EventSequenceNumber = 1   String EventSchemaVersion = "7.0.5000.0"   DateTime TimeStamp = 8/18/2003 1:09:43 PM   String AppDomainName = "/LM/w3svc/1/root/NorthwindSite-2-127056712222343750"   String MachineName = "NORTHWIND-LONDON-01"   String RootRequestName = ""   String RootRequestInstance = ""   String RequestInstance = ""   String RequestName = ""   Int64 RequestSequenceNumber = 0   Int32 EventLogEntryTypeID = 4}

Issues with ASP.NET Applications

If you are using EIF to instrument ASP.NET applications or Web services, you need to be aware of the following issues:

Using the Windows Event Log. The ASPNET local account cannot register a Windows Event Log event source, but it can write events if the event source has already been registered by an administrator. To handle this issue, make sure that the local user is a local administrator before running InstallUtil against the application's instrumented assemblies.
Using WMI. The ASPNET account cannot fire WMI events on Windows XP (prior to SP1) and Windows 2000 (prior to SP3). Install the latest service pack to fix this issue. If you cannot install the latest service pack, you can use the workaround described in the topic, "Raising Events from ASP.NET Web Applications," in the EIF documentation.

Additional Resources

For more information about EIF, see the EIF documentation. The documentation installed with EIF contains reference materials and walk-throughs for more complex instrumentation examples.

The documentation is provided as a compiled help file (.chm) at the following location.

C:\Program Files\Microsoft Enterprise 
Instrumentation\Docs\EnterpriseInstrumentation.chm

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.