The Performance Counter Handler

Article
05/09/2013

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.
The latest Enterprise Library information can be found at the Enterprise Library site.

The Performance Counter Handler increments a specific counter each time it executes in response to invocation of the selected method or setting of the selected property. This handler uses the instrumentation features that are part of the Enterprise Library Core.

The Performance Counter Handler applies both before and after invocation of the selected method or access to the selected property of the target object. The handler can increment different types of counters and increment more than one counter each time (such as a single instance and a total counter).

Installing and Removing Performance Counters

To use the Performance Counter Handler, you must first install the performance counters into the operating system. You can use the Installutil.exe utility that ships with the .NET Framework to install or uninstall the performance counters.

installutil.exe /category=<category>[;<category> ...] Microsoft.Practices.EnterpriseLibrary.PolicyInjection.CallHandlers.dll

Alternatively, the Policy Injection Application Block includes a utility class named PerformanceCountersInstaller that you can use to install the appropriate counters. The file PerformanceCountersInstaller.cs that contains this class is in the Installers subfolder of the application block. The PerformanceCountersInstaller class inherits from the Installer class in the System.Configuration namespace, which exposes methods to install and uninstall performance counters.

To install the performance counters required by the Performance Counter Handler, the client application must create a new instance of the PerformanceCountersInstaller class using the default configuration source. The constructor of the PerformanceCountersInstaller class automatically reads the performance counter categories defined in the application configuration. After that, the code can create a new hash table to hold the counter state and an instance of the InstallContext class to hold the parameters for the counters, which it assigns to the Context of the PerformanceCountersInstaller instance. To install the counters, the code then calls the Install and Commit methods of the PerformanceCountersInstaller instance, passing the hash table containing the state to each one.

PerformanceCountersInstaller = new PerformanceCountersInstaller(new SystemConfigurationSource());
IDictionary state = new System.Collections.Hashtable();
installer.Context = new InstallContext();
installer.Install(state);
installer.Commit(state);
MessageBox.Show("Performance counters have been successfully installed.",
                 this.Text, MessageBoxButtons.OK, MessageBoxIcon.Information);

'Usage
Dim installer As New PerformanceCountersInstaller(New SystemConfigurationSource())
Dim state As New System.Collections.Hashtable()
installer.Context = New InstallContext()
installer.Install(state)
installer.Commit(state)
MessageBox.Show("Performance counters have been successfully installed.", _
                  Me.Text, MessageBoxButtons.OK, MessageBoxIcon.Information)

To uninstall the performance counters for the Performance Counter Handler, the client application again creates an instance of the PerformanceCountersInstaller class and the InstallContext class, and then it calls the Uninstall method of the PerformanceCountersInstaller instance.

PerformanceCountersInstaller installer = new PerformanceCountersInstaller(new SystemConfigurationSource());
installer.Context = new InstallContext();
installer.Uninstall(null);
MessageBox.Show("Performance counters have been successfully uninstalled.", 
                  this.Text, MessageBoxButtons.OK, MessageBoxIcon.Information);

'Usage
Dim installer As New PerformanceCountersInstaller(New SystemConfigurationSource())
installer.Context = New InstallContext()
installer.Uninstall(Nothing)
MessageBox.Show("Performance counters have been successfully uninstalled.", _
                  Me.Text, MessageBoxButtons.OK, MessageBoxIcon.Information)

The PerformanceCountersInstaller class overrides the OnBeforeInstall and OnBeforeUninstall methods of the Installer base class to generate the category for the counters exposed by the Performance Counter Handler, and it populates the category with the counter instances for the handler.

The PerformanceCountersInstaller class also exposes overloads of the constructor that accept a String collection containing the category names to install or uninstall and a default constructor that generates an empty list of categories.

Behavior of the Performance Counter Handler

In more detail, the Performance Counter Handler does the following:

It reads details of the counters to increment, including the counter type and counter method name, from the Policy Injection Application Block configuration.
It increments any counters configured for inclusion in the pre-processing stage.
It invokes the selected target method or sets the selected target property.
It increments any counters configured for inclusion in the post-processing stage.
It is configurable to work with counters of the following types:
- Total number of calls to the target method or property
- Average number of calls to the target method or property per second
- Average duration of calls to the target method or property
- Total number of exceptions encountered during calls to the target method or property
- Average number of exceptions encountered per second during calls to the target method or property per second
- Percentage of exceptions to successful calls for the target method or property

Configuration Settings of the Performance Counter Handler

The following configuration settings are available for the Performance Counter Handler:

CategoryName (String). This is the category name of the target performance counter. The counter must already exist.
InstanceName (String). This is the instance name of the target performance counter, which can include the following tokens:
- {method}
- {type}
- {namespace}
- {assembly}
- {appdomain}
IncrementAverageCallDuration (Boolean). This specifies whether the handler should increment an "Average call duration" counter each time. The default setting is True.
IncrementCallsPerSecond (Boolean). This specifies whether the handler should increment a "Number of calls per second" counter each time. The default setting is True.
IncrementExceptionsPerSecond (Boolean). This specifies whether the handler should increment a "Number of exceptions per second" counter each time. The default setting is False.
IncrementNumberOfCalls (Boolean). This specifies whether the handler should increment a "Total number of calls" counter each time. The default setting is True.
IncrementTotalExceptions (Boolean). This specifies whether the handler should increment a "Total number of exceptions" counter each time. The default setting is False.
UseTotalCounter (Boolean). This specifies whether the handler should increment a counter that shows the total of all the other counters. The default setting is True.
Order (Integer). This value specifies the position of the handler within the policy handler chain. The default value is zero, which means that there is no explicit order specified for the handler in relation to other handlers in the same handler chain. To specify an explicit order, set the Order property for each handler starting from 1. If you specify the same value for the Order property of two handlers in the same policy, the application block will add them to the policy handler chain in the order defined in the configuration.

The next procedure describes how to configure the Performance Counter Handler using the Configuration Console or the Visual Studio Configuration Editor.

To configure the Performance Counter Handler

Before you configure and run an application that uses the Performance Counter Handler, you must install the appropriate performance counters into the operating system. For more information, see "Installing and Removing Performance Counters" earlier in this topic.
Right-click the Handlers node in the Enterprise Library Configuration Console or Visual Studio Configuration Editor, point to New, and then click Performance Counter Call Handler.
In the right pane of the Enterprise Library Configuration Console, or in the Visual Studio Properties window, select the Name property, and then change the default to the name you want to use for the new handler.
Select the CategoryName property, and then enter the name of the performance counters category you created when installing the counters into the operating system.
Select the InstanceName property, and then enter the name of the performance counters instance you created when installing the counters into the operating system.
Select the IncrementAverageCallDuration property, and then click True in the drop-down list if you want to record the average time taken for calls to the target object member or click False if you do not want to record this information.
Select the IncrementCallsPerSecond property, and then click True in the drop-down list if you want to record the average number of calls to the target object member occurring each second or click False if you do not want to record this information.
Select the IncrementExceptionsPerSecond property, and then click True in the drop-down list if you want to record the average number of exceptions raised by the target object member each second or click False if you do not want to record this information.
Select the IncrementNumberOfCalls property, and then click True in the drop-down list if you want to record the total number of calls made to the target object member or click False if you do not want to record this information.
Select the IncrementTotalExceptions property, and then click True in the drop-down list if you want to record the total number of exceptions raised by calls to the target object member or click False if you do not want to record this information.
Select the UseTotalCounter property, and then click True in the drop-down list if you want to record the total of all the other counters or click False if you do not want to record this information.
(Optional) Enter a numeric value for the Order property if you want to specify the position of the handler within the policy handler chain. Set the Order property for each handler starting from 1.

Attribute-based Targeting with the Performance Counter Handler

The following code shows the use of the PerformanceCounterCallHandler attribute on a simple method. This attribute can also be applied to the class declaration, in which case it applies to all members of that class. The category name and instance name of the counter to update are mandatory parameters of the PerformanceCounterCallHandler attribute.

[PerformanceCounterCallHandler("category-name", "instance-name")]
public void Deposit(decimal depositAmount)
{
  balance += depositAmount;
}

'Usage
<PerformanceCounterCallHandler("category-name", "instance-name")> _
Public Sub Deposit(Decimal depositAmount)
  balance += depositAmount
End Sub

The following table describes the properties of the PerformanceCounterCallHandlerAttribute class.

Property	Description
CategoryName	String. The name of the category name of the target performance counter.
InstanceName	String. The name of the instance of the target performance counter. Can include the tokens {method}, {type}, {namespace}, {assembly}, and {appdomain}.
IncrementAverageCallDuration	Boolean. Whether to increment an "Average duration of each call" counter each time.
IncrementCallsPerSecond	Boolean. Whether to increment a "Number of calls per second" counter each time.
IncrementExceptionsPerSecond	Boolean. Whether to increment a "Number of exceptions per second" counter each time.
IncrementNumberOfCalls	Boolean. Whether to increment a "Total number of calls" counter each time.
IncrementTotalExceptions	Boolean. Whether to increment a "Total number of exceptions" counter each time.
UseTotalCounter	Boolean. Whether to increment a "Total" counter each time.
Order	Integer. The position of the handler within the policy handler chain, starting from 1. The default value is zero, which means that there is no explicit order specified for the handler in relation to other handlers in the same handler chain.

To set these properties using an attribute, add them as parameters to the attribute declaration, as shown in the following code.

[PerformanceCounterCallHandler(CategoryName="My Category", 
                               InstanceName="MyInstance", UseTotalCounter=false)]

'Usage
<PerformanceCounterCallHandler(CategoryName:="My Category", _
                               InstanceName:="MyInstance", UseTotalCounter:=False)>

Share via

The Performance Counter Handler

Installing and Removing Performance Counters

Behavior of the Performance Counter Handler

Configuration Settings of the Performance Counter Handler

Attribute-based Targeting with the Performance Counter Handler

Additional resources