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.

Event class	Description
WebApplicationLifetimeEvent	Represents a significant event in the lifetime of an ASP.NET application. Application lifetime events include events such as application startup and shutdown events. If an application is terminated, you can determine why by viewing the related event-message field.
WebAuditEvent	Serves as the base class for all ASP.NET health-monitoring audit events.
WebAuthenticationFailureAuditEvent	Provides information about ASP.NET authentication failures.
WebAuthenticationSuccessAuditEvent	Provides information about successful authentication events.
WebBaseErrorEvent	Serves as the base class for all the health-monitoring error events.
WebBaseEvent	Serves as the base class for the ASP.NET health-monitoring events.
WebErrorEvent	Provides information about errors caused by problems with configuration or application code. An example is the error issued by ASP.NET when an error is found in a page.
WebFailureAuditEvent	Provides information about security failures.
WebHeartbeatEvent	Serves as a timer for the ASP.NET health-monitoring system. These events are raised at an interval defined by the heartbeatInterval attribute of the healthMonitoring configuration section.
WebManagementEvent	Serves as the base class for events that carry application and process information.
WebRequestErrorEvent	Defines the event that carries information about Web-request errors.
WebRequestEvent	Serves as the base class for events providing Web-request information.
WebSuccessAuditEvent	Provides information about successful security events. An example of this is a successful URL authorization for a Web request.
WebViewStateFailureAuditEvent	Provides Web-application view state failure information.

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.

Event Providers	Details
EventLogWebEventProvider	Writes Web event data to the Windows event log. By default, this provider is configured to write all errors to the Windows event log. Security operation errors are logged under the event name Failure Audits and logs all other errors are logged under the event name All Errors. To read event log data, you can view data using the Windows Event Viewer or read event log data programmatically. For more information, see Reading the Event Log.
SqlWebEventProvider	Logs Web event data to a Microsoft SQL server database. By default, this provider logs data to the SQL Server Express database in the Web application's App_Data folder. It does not subscribe to any events by default.
WmiWebEventProvider	Passes Web events to WMI, converting them to WMI events. By default, this provider does not subscribe to any events. To listen for WMI events, you can build an application such as the one illustrated in Walkthrough: Listening for WMI Events in ASP.NET Health Monitoring. For more information, see Using WMI to Deliver ASP.NET Health Monitoring Events. WMI applications do not have to be written in managed code.
SimpleMailWebEventProvider and TemplatedMailWebEventProvider	Sends an e-mail message when Web events are raised. By default, these providers are not configured and do not subscribe to any events.
TraceWebEventProvider	Passes event data to the ASP.NET page tracing system. By default, this provider is not configured and does not subscribe to any events. Tracing provides you the ability to start and stop event tracing sessions, to instrument applications to provide trace events, and to consume trace events. You can use the events to debug an application and perform capacity and performance analysis. For more information, see ASP.NET Tracing.

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