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 Administering ASP.NET Web Sites.

   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. Bothare enabled and are subscribed to by the EventLogProvider.

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.

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

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.

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

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.

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.