Instrumentation

In Enterprise Library, the interfaces and classes responsible for logging events to the Windows Event Log or updating Windows Performance Counters are separated from those that indicate an instrumentation-worthy activity has occurred.

Each application block contains one or more classes responsible for translating activities from within the block into Event Log messages or Performance Counter updates. These classes are generally known as instrumentation providers because they provide instrumentation services within that block. Classes within an application block use the instrumentation providers to indicate that an activity has occurred.

Each block is responsible for a different set of activities and so the exact interface of the provider varies for each block. For example, the instrumentation provider interface for the CachingInstrumentationProvider class is as follows:

public interface ICachingInstrumentationProvider
{
  void FireCacheUpdated(long updatedEntriesCount, long totalEntriesCount);
  void FireCacheAccessed(string key, bool hit);
  void FireCacheExpired(long itemsExpired);
  void FireCacheScavenged(long itemsScavenged);
  void FireCacheCallbackFailed(string key, Exception exception);  
  void FireCacheFailed(string errorMessage, Exception exception);
}

The Cache class in the Caching Block uses an ICachingInstrumentationProvider each time it must indicate the cache was accessed. When the cache is accessed it calls the FireCacheAccessed method of the instrumentation provider.

The instrumentation providers are typically connected to other classes within the block through a constructor parameter. The Cache class, for example, takes an ICachingInstrumentationProvider as shown here.

public class Cache : ICacheOperations, IDisposable
{    
    public Cache(IBackingStore backingStore, 
                 ICachingInstrumentationProvider instrumentationProvider)
    {
      ...
    }
    ...
}

Because the implementations for the instrumentation provider interfaces are registered within the dependency injection container, they are injected into the classes that require them.

How Instrumentation Providers Work

Instrumentation providers handle the details of installing and updating the Event Log and Windows Performance Counters. For historical reasons, all providers derive from InstrumentationListener. InstrumentationListener provides base functionality to determine by examining its constructor parameters if event logging and performance counters are currently enabled within an Enterprise Library enabled application, and exposes routines to assist the instrumentation provider in writing to the Event Log and Performance Counters.

Each instrumentation provider in Enterprise Library indicates the set of Performance Counters and Event Logs it writes to through a series of attributes applied to the provider, as shown in the following table. It also carries the HasInstallableResources attribute to indicate that it defines instrumentation.

Attribute	Description
PerformanceCountersDefinitionAttribute	Indicates the categories for a performance counter.
PerformanceCounterAttribute	Indicates performance counter to use, the help text for the counter, and the type of performance counter.
EventLogDefinitionAttribute	Indicates the Event Log to write to and the source name to use.

For an instrumentation provider to be able to successfully write to an Event Log or a Performance Counter, the Event Log sources and Performance Counters must be registered with the operating system. Each block that has an instrumentation provider also provides an installer class that can be processed by the InstallUtil.exe utility.

The block-specific installer for Enterprise Library evaluates the attributes on each of its instrumentation providers to discover which Event Log and Performance Counters should be registered with the operating system, and registers them.

If you have turned off instrumentation for your application, the instrumentation providers will not attempt to update Performance Counters or write to the Event Log. In this case, you do not need to execute InstallUtil.exe as the artifacts it creates will not be used by the application.