Enabling Instrumentation

The term instrumentation refers to a system's built-in ability to monitor or measure performance and to diagnose errors. Enterprise Library incorporates the following instrumentation in the majority of the application blocks:

• Event logs. The application blocks inform users of key events, such as errors or warnings.
• Performance counters. The application blocks record key metrics—such as the number of critical events that occur per second or the average time it takes to complete key tasks—by writing to the Microsoft Windows® operating system performance counters.

For details of the design of the Enterprise Library instrumentation, see Instrumentation.

Enabling and Disabling Instrumentation

By default, instrumentation is disabled. To enable instrumentation, you must install the instrumentation schema and configure your application.

Installing and Uninstalling the Instrumentation Schema

To install the instrumentation schema, you can either run the InstallServices.bat batch file or you can use the Install Instrumentation shortcut on the Start menu. To use the shortcut, click Start, point to All Programs, point to Microsoft patterns & practices, point to Enterprise Library 5.0, and then click Install Instrumentation.

To uninstall instrumentation, you can either run the InstallServices.bat batch file with the /u parameter or you can use the Uninstall Instrumentation shortcut on the Start menu. To use the shortcut, click Start, point to All Programs, point to Microsoft patterns & practices, point to Enterprise Library 5.0, and then click Uninstall Instrumentation.

Configuring an Application for Instrumentation

Instrumentation is controlled by the <instrumentationConfiguration> section of the application's configuration file. This section determines how instrumentation behaves for the entire application.

By default, each type of instrumentation is disabled. You can use configuration to enable each type of instrumentation or to disable instrumentation if you have previously enabled it. All instrumentation properties appear in the Instrumentation Settings pane. When a property is set to True, the instrumentation is enabled. When a property is set to False, the instrumentation is disabled.

To configure instrumentation

1. Start the configuration console or the Visual Studio configuration editor.

2. To edit an existing application configuration, open the File menu and click Open, then select the configuration file for your application.

3. On the Blocks menu, click Add Instrumentation Settings.

4. If the properties are not displayed in the Instrumentation Settings pane, click on the properties expander chevron.

   

5. In the properties pane for the Event Logging Enabled property, select True or False. The default value is False.

6. In the properties pane for the Performance Counters Enabled property, select True or False. The default value is False.

7. (Optional) In the properties pane for the Protection Provider property, you can select RsaProtectedConfigurationProvider or DataProtectedConfigurationProvider as the provider used to encrypt the configuration file. The default is no protection. See Encrypting Configuration Data for information about the restrictions on using the RsaProtectedConfigurationProvider.

8. (Optional) In the properties pane for the Require Permission property, select True or False. The default is True, which allows the application to run in partial trust modes.

9. (Optional) In the properties pane for the Application Instance Name type a name.

10. (Optional, not shown above) If you have configured a run-time environment, set the override property. By default this is set to Don't Override Properties and any overridable properties are disabled.