ASP.NET Health Monitoring Overview

ASP.NET provides an easy way to monitor the health of deployed ASP.NET applications, providing you with detailed run-time information about ASP.NET resources. ASP.NET health-monitoring features can be used to perform the following tasks:

• Monitor live ASP.NET applications, individually or across a Web farm, to ensure that they are working properly.

• Diagnose ASP.NET applications that appear to be failing.

• Log events that do not necessarily relate to errors in an ASP.NET application but can be useful for you to examine.

In the past, Web site administrators had to rely on HTTP errors, debugging output, or a limited set of event log messages to monitor or diagnose their applications in a reactive manner. ASP.NET health monitoring provides a proactive approach by raising Web events and delivering health-monitoring data through various mechanisms.

Note
You can also use ASP.NET tracing or debugging to diagnose errors in ASP.NET pages or applications. For more information, see ASP.NET Tracing and ASP.NET Debugging. You can also monitor the performance of your ASP.NET application. For more information, see ASP.NET Performance.

This topic contains the following sections:

• How ASP.NET Health Monitoring Works

• Web Events

• Consuming Web Events Using Event Providers

• Enabling and Disabling Web Events

• Effect of Health Monitoring on Performance

• Extending ASP.NET Health-Monitoring Features

• Securing ASP.NET Health Monitoring

How ASP.NET Health Monitoring Works

ASP.NET can raise Web health-monitoring events (also called Web events) at various times during the course of application processing. Web events are consumed by providers (listeners), which read the information packaged with the event and then record the information. Each provider is written to record the Web event data in a different way. For example, one provider might write to the Windows event log, while another might send an e-mail message.

The following list shows step-by-step how health monitoring works:

1. ASP.NET builds a merged collection of application configuration settings when an application starts. For more information, see ASP.NET Configuration File Hierarchy and Inheritance. Providers and events are registered in the configuration settings for the application.

2. A Web health-monitoring event (a Web event) occurs. For example, this can be an event caused by a security operation that fails, such as a failure during URL authorization for a Web request.

3. ASP.NET checks the configuration settings for registered providers and events. Health-monitoring configuration settings are contained in the healthMonitoring element of configuration files. For information about how to configure ASP.NET applications, see Configuring ASP.NET Applications.

   The following health-monitoring settings are required.

   • Types of Web events are assigned to named groups in the eventMappings collection element. For example, events that occur when a security operation fails are named Failure Audits and are mapped by default to the WebFailureAuditEvent class in the root Web.config configuration file, using an element such as the following:

     <eventMappings>
       <add
         name="Failure Audits"    type="System.Web.Management.WebFailureAuditEvent"
         <!-- additional attributes here -->
       />
       <!-- additional <add> elements here -->
     </eventMappings>
     

   • Types of event providers (listeners) are assigned to event provider classes in the providers collection element. For example, the event provider that consumes all error events is named EventLogProvider and is mapped to the EventLogWebEventProvider class in the root Web.config configuration file, using an element such as the following:

     <providers>
       <add 
         name="EventLogProvider"    type="System.Web.Management.EventLogWebEventProvider"
         <!-- additional attributes here for some providers -->
       />
       <!-- additional <add> elements here -->
     </providers>
     

   • Event providers subscribe to events in the rules collection element. Event providers can subscribe to more than one Web event, and Web events can be subscribed to by more than one event provider. By default, the EventLogProvider subscribes to the Failure Audits events in the root Web.config file, using an element such as the following:

     <rules>
       <add
         name="Failure Audits Default"    eventName="Failure Audits"    provider="EventLogProvider" 
         <!-- additional attributes here -->
       />
     </rules>
     

4. When an event is raised, an instance of the Web event class is created. Event data is collected in the properties of this object. For example, the properties of the WebFailureAuditEvent object include information about the event identifier, source, date and time, and a special WebApplicationInformation class that contains information about the application domain, path, and so on. Built-in events are raised automatically by ASP.NET. Custom events must be explicitly raised using the Raise method.

5. The event provider consumes the event and records the event information. For example, the EventLogProvider writes event information to the Windows event log. Other providers deliver event data using different mechanisms. For more information, see Consuming Web Events Using Event Providers below.

ASP.NET comes with built-in Web events and providers already configured as system defaults. However there are only two events enabled in the rules element: All Errors and Failure Audits. Both are enabled and are subscribed to by the EventLogProvider.

Web Events

Web events can contain information about the ASP.NET worker process, application domain, request data, response data, application errors, and configuration errors. The following managed Web event classes are available in ASP.NET as members of the System.Web.Management namespace. All event classes inherit from the WebBaseEvent base class. For information about how to obtain event data, see Consuming Web Events Using Event Providers later in this topic.

By default, ASP.NET automatically records some Web event data. For example, some event data, such as the number of times that an event occurs, is captured using performance counters. In these situations, performance counters are used instead of Web events to minimize the impact on the performance of health-monitored applications. This behavior is not customizable. For more information, see ASP.NET Performance, performance counters, and the Performance monitoring pages in MSDN.

Customizing Events

You can customize Web events in the following ways:

• You can limit the number of event notifications that occur in a given time span and specify the interval between events using attributes of the rules element. The following example shows a fragment from the configuration file in which the Default profile is configured for Failure Audit events. The Default profile specifies the following settings

  • The minimum number of times an event can occur before an event notification is sent is 1.

  • The maximum number of times an event can occur before notifications stop is 2147483647 (infinite).

  • The minimum time interval between two events is one minute.

  <rules>
    <add
      name="Failure Audits Default"
      eventName="Failure Audits"
      provider="EventLogProvider" 
      profile="Default" 
      minInstances="1"    maxLimit="Infinite"    minInterval="00:01:00"
      custom="" 
    />
    <!-- additional <add> elements here -->
  </rules>
  

• You can subscribe an existing provider or a custom provider to a Web event by configuring a new rules element in your Web.config file. The following example code shows how the EventLogWebEventProvider subscribes to a custom event named SampleCustomWebEvent. The EventLogProvider is already configured in the root Web.config file.

  <rules>
    <add 
      name="Sample Custom Events" 
      eventName="SampleCustomWebEvent" 
      provider="EventLogProvider"
      profile="Default" 
      minInstances="1" 
      maxLimit="Infinite" 
      minInterval="00:01:00"
      custom="" 
    />
  </rules>
  <eventMappings>
    <add 
      name="SampleCustomWebEvent" 
      type="Microsoft.Samples.Web.Management.SampleCustomWebEvent"
      startEventCode="0" 
      endEventCode="2147483647" 
    />
  </eventMappings>
  

If none of the built-in event classes meets your needs, you can create custom events by inheriting from existing event classes. For more information, see Extending ASP.NET Health Monitoring.

Note
Do not place the source code that you create for custom event providers and custom Web events in the App_Code directory. Instead, compile the source code into assemblies and place those assemblies in the Bin directory. For more information on application folders, see ASP.NET Web Site Layout.

Consuming Web Events Using Event Providers

Event providers consume Web event data. By default, the ASP.NET health-monitoring system can deliver Web event data using the built-in providers listed in the following table. More than one provider can listen for the same event, and more than one event can be consumed by the same provider. For information about subscribing event providers to Web events, see Enabling and Disabling Web Events below.

Customizing Event Providers

You can customize event providers in the following ways:

• You can buffer event data that will be consumed by the SQL or mail event providers. For more information, see Buffering ASP.NET Health Monitoring Events.

• You can configure event providers to consume existing or custom Web events by configuring a new rules element in your Web.config file. The following example shows how the MyCustomEventProvider subscribed to the WebHeartbeatEvent. The Heartbeats event is already configured in the root Web.config file.

  <rules>
    <add 
      name="Heartbeat Events" 
      eventName="Heartbeats" 
      provider="Sample Custom Event Provider"
      profile="Default" 
      minInstances="1" 
      maxLimit="Infinite" 
      minInterval="00:01:00"
      custom="" 
    />
  </rules>
  <providers>
    <add 
      name="Sample Custom Event Provider" 
      type="System.Web.Management.SampleCustomEventProvider" 
    />
  </providers>
  

• You can create your own custom event providers by inheriting from the WebEventProvider or BufferedWebEventProvider classes. Custom event providers can be used to log events to a custom log file, send event data to third-party applications, and so on. For more information, see Extending ASP.NET Health Monitoring. For code examples, see Implementing Custom ASP.NET Health Monitoring Events and Providers.

Enabling and Disabling Web Events

An event is enabled if it is mapped to an event provider in the rules element of a configuration file. The eventMappings and the providers element must also be configured for the event and provider, but unless the two are connected in the rules element, the event is not raised. For more information, see Configuring ASP.NET Health Monitoring.

To disable an event, you can remove all references to the event from the rules configuration collection.

Effect of Health Monitoring on Performance

The performance of your application is affected by how extensively you use ASP.NET health-monitoring features. To minimize the impact on the performance of health-monitored applications, configure the minInterval attribute of the rules element to increase minimum time interval between two events.

Event Buffering

You can configure the SqlWebEventProvider and MailWebEventProvider event providers to buffer events. Buffering collects event data and sends it all at once instead of logging the information or sending an e-mail message immediately when the event occurs. This helps to minimize the impact of health monitoring on application performance. In addition, event buffering also protects SQL Server and the SMTP server from heavy loads due to high event volume. For more information, see Buffering ASP.NET Health Monitoring Events, BufferedWebEventProvider, and the bufferModes Element.

Extending ASP.NET Health-Monitoring Features

If you already have a monitoring infrastructure, you can integrate ASP.NET health-monitoring system into it. For example, WMI can be used to capture ASP.NET Web events and record the data using an existing data store.

Using the classes of the System.Web.Management namespace, you can create custom Web events or custom event providers. For more information, see Extending ASP.NET Health Monitoring.

Securing ASP.NET Health Monitoring

By default, the ASP.NET health-monitoring system is configured to protect sensitive data and protect against performance issues. For more information, see Securing ASP.NET Health Monitoring.

See Also

Reference

healthMonitoring Element (ASP.NET Settings Schema)
System.Web.Management

Concepts

ASP.NET Web Site Layout

Other Resources

ASP.NET Health Monitoring