ASP.NET Health Monitoring Overview

ASP.NET health monitoring enables system administrators to monitor the status of deployed Web applications.

This topic contains:

• Scenarios

• ASP.NET Health Monitoring Features

• Background

• Code Examples

• Class Reference

Scenarios

ASP.NET health monitoring enables you to do the following tasks:

• Monitor the performance of an application to make sure that it is healthy.

• Rapidly diagnose applications or systems that are failing.

• Appraise significant events during the life cycle of an application.

• Monitor live ASP.NET applications, individually or across a Web farm.

• Log events that do not necessarily relate to errors in an ASP.NET application.

Back to top

Features

The ASP.NET health monitoring system includes:

• Event types that package application health status information.

• Provider types that process event information.

• Additional types that help you manage health events.

Back to top

Background

ASP.NET health monitoring gives you an easy way to monitor the health of an ASP.NET application and to get detailed run-time information about ASP.NET resources (to instrument the application). Health monitoring contains ready-to-use Web health-monitoring events classes (Web events) and health-monitoring providers (listeners). Web events package health-event information.

Providers listen for events and consume the event information, typically by logging the information or by notifying an administrator. You connect a Web event to a provider (referred to as enabling the event) by making settings in the application's configuration file.

The ASP.NET health monitoring system is implemented by using classes in the System.Web.Management namespace.

Configuring ASP.NET Health Monitoring

You can configure applications to use built-in or customized monitoring providers that process health-monitoring information and that report on the health status and the performance characteristics of the instrumented application.

You add Web events and providers to an application by configuring the healthMonitoring section in the configuration file. You then use built-in or custom classes to listen for the event data and process it.

For more information about configuration files, see ASP.NET Configuration Files.

Web Event class Hierarchy

When a Web event is raised, an instance of the associated event class is created. Event data is collected in the properties of this object. Event providers process this data.

Web events can contain information about the worker process, application domain, request data, response data, application errors, configuration errors, and audit events. Health information that is contained in a parent event class is inherited by any child event classes.

The relationships between Web event classes are shown in the following illustration.

Web event class hierarchy

The further down an event is in the hierarchy of Web event classes, the more specific the data is to the ASP.NET application. For example, derived classes can expose information such as stack traces, client IPs, and thread and process information.

Web Event Information

The following table lists information that helps you decide what Web event class to use or to inherit from. The rows refer to the Web event classes. The columns refer to the information classes, which are usually made available as properties in the Web event classes.

If your application is not running with Full trust, only the WebBaseEvent class is inheritable. This helps protect against exposing sensitive information through the information classes listed in the table.

Provider Class Hierarchy

ASP.NET includes built-in providers that can you can use to process Web events. You can also inherit from built-in classes to create a custom provider, subject to the following inheritance limitations:

• The WebEventProvider class can be inherited by applications that run under any trust level.

• The BufferedWebEventProvider class can be inherited by applications that run under any trust level.

• The SqlWebEventProvider class can be inherited only by applications that run under Full trust.

Other classes cannot be inherited by applications, regardless of trust level. For more information, see the class overviews for individual provider classes.

The following illustration shows the relationship between the Web provider classes of the System.Web.Management namespace.

Web provider class hierarchy

Using ASP.NET Health-monitoring Events

You can work with ASP.NET health-monitoring events in the following ways:

• Use built-in Web event and provider classes. You typically do not have to provide custom implementations of any ASP.NET Web event classes. Note that your application does not raise these events, the .NET Framework does. However, you must configure them as explained later in this topic. For more information, see How to: Send E-mail for Health Monitoring Notifications.

• Create custom classes for Web events or providers. You typically create custom Web events if you must append custom information to what is already provided by the built-in Web events. You typically create custom providers if you want to deliver event data through a mechanism other than that available with the built-in providers. For more information, see Extending ASP.NET Health Monitoring Events.

Using Built-in Web Events and Providers

Using built-in Web events and providers for health monitoring is the most common strategy. It requires only that you configure the application to use the events and providers that you need. You must do the following:

• Add the built-in ASP.NET Web event class that you need to the eventMappings element of the healthMonitoring section in the application's configuration file.

• Add the provider that consumes the event to the providers element of the healthMonitoring section.

• Add an item to the rules element that defines the association between the event and the provider.

By default, the built-in ASP.NET health monitoring classes are configured in the healthMonitoring section of the root Web.config file. The healthMonitoring section establishes the following default configuration:

• All the Web event classes that derive from WebBaseEvent are specified in the eventMappings element. This section is used to assign a friendly name to a group of event classes.

• All event classes that derive from WebBaseEvent are included in at least one of the groups that is defined in the eventMappings element.

The EventLogWebEventProvider, WmiWebEventProvider, and SqlWebEventProvider event providers are specified in the providers element. You can specify other built-in providers in the providers element, such as the SimpleMailWebEventProvider, TemplatedMailWebEventProvider, or TraceWebEventProvider classes.

The rules that associate the Web error and audit failure events to the EventLogWebEventProvider classes are specified in the rules element. You can enable other Web events and providers by adding more rules elements. An event is considered enabled if it is mapped to an event provider in the rules element. The eventMappings and the providers elements must be configured for the event, but unless the two are connected in the rules element, the event is not enabled.

You can specify parameter values for the configured items. Examples include parameters that limit the number of events that can occur, that specify the interval between two events, or that specify event buffering options for the SQL and mail providers.

Configuring a Custom Provider

If you require custom processing of Web event information, you can build a custom health event provider. Your provider is a class that inherits from the WebEventProvider or the BufferedWebEventProvider class. For an example, see How to: Implement the Health Monitoring Custom Provider Example. Creating a custom provider is the most common health-monitoring customization. It requires that you modify the configuration file in the following ways:

• Add the custom provider that processes the event to the providers element of the healthMonitoring section in the configuration file.

• Add an item to the rules element that defines the association between the event and the provider.

• Put the assembly that contains the custom provider implementation in the application's Bin subdirectory. You cannot put the provider source code file in the App_Code subdirectory, because the health monitoring system is configured and created before any code files in the App_Code subdirectory are compiled.

The type attribute of the providers element requires at least the class name. If the assembly is not located in the application's Bin directory, the assembly must be strongly named and installed in the global assembly cache. In that case, the type attribute of the providers element requires the complete strong name, as shown in the following example, where the Version and PublicKeyToken values match your assembly:

type="Microsoft.Samples.Web.Management.SampleCustomEventProvider, Sample.SampleCustomEventProvider,Version=n.n.n.n,Culture=neutral, PublicKeyToken=xxxx"

The following example shows how to associate the SampleCustomEventProvider provider with the WebHeartbeatEvent event. The Heartbeats event is already configured in the root Web.config file.

<healthMonitoring 
  heartBeatInterval="1" 
  enabled="true">
  <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="Microsoft.Samples.Web.Management.SampleCustomEventProvider, Sample.SampleCustomEventProvider,Version=1.0.0.0,Culture=neutral, PublicKeyToken=xxxxxxxxxxxx" 
    />
  </providers>
</healthMonitoring>

Configuring a Custom Event

If you require custom health event information, you can build a custom health event. For an example, see How to: Implement and Raise Custom ASP.NET Health Monitoring Events. Creating a custom Web event is less common than creating a custom provider. It requires that you modify the configuration file. You must also explicitly raise the custom event at the appropriate time.

To configure the event, you must do the following:

• Add the custom health event class to the eventMappings element of the healthMonitoring section.

• Add a rules element that defines the association between the event and the provider.

• Add the assembly that contains the custom Web event implementation to the Bin subdirectory of the ASP.NET application. Alternatively, you can add the event source code file to the App_Code subdirectory.

If you use an assembly, the type attribute of the eventMappings element requires at least the class name and the assembly file name, as shown in the following code example:

type="System.Web.Management.SampleCustomWebEvent, Sample.SampleCustomWebEvent"

If you use a source code file, you must specify only the class name.

The following example shows how to associate the EventLogWebEventProvider event provider with a custom event named SampleCustomWebEvent. The EventLogProvider event provider is already configured in the root Web.config file.

<healthMonitoring 
  heartBeatInterval="0" 
  enabled="true">
  <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="System.Web.Management.SampleCustomWebEvent, Sample.SampleCustomWebEvent,Version=1.0.0.0,Culture=neutral, PublicKeyToken=xxxxxxxxxxxx" "
      startEventCode="0" 
      endEventCode="2147483647" 
    />
  </eventMappings>
</healthMonitoring>

Securing ASP.NET Health Monitoring

By default, the health monitoring feature is enabled for ASP.NET applications. You can disable it by setting the enabled attribute of the healthMonitoring element to false. The default configuration settings are set to the most secure values that are available. For more information about health monitoring configuration settings, see healthMonitoring. Consider locking the health monitoring configuration settings by using the location element.

Securing Configuration Values

When you store sensitive information in a configuration file for an application, you should encrypt the sensitive values by using protected configuration. Information that is especially sensitive includes the encryption keys that are stored in the machineKey configuration element, and connection strings to a data source that are stored in the connectionStrings configuration element. For more information, see Encrypting Configuration Information Using Protected Configuration.

The healthMonitoring configuration section can be accessed only by code that uses medium trust or higher. This prevents low-trust applications from registering custom types.

Security for Extending Health Monitoring

The health monitoring types in the System.Web.Management namespace have the following characteristics:

• Base class constructors are marked as protected internal. Therefore, instances of base class event types cannot be created directly by user code.

• Access to Web event instances is limited to configuration-specified providers, filters, and template pages.

• Inheritance link demands on events with protected content make sure that only fully trusted custom events can be derived.

• Custom trusted events that expose sensitive data from protected event properties must enforce code access security themselves to avoid luring attacks. For details about code access security, see ASP.NET Code Access Security or Code Access Security Basics.

• The Windows Management Instrumentation (WMI) types that are used to view Web events are locked to prevent all users from accessing event data.

  Note

  When you implement custom event consumers or custom event providers, you must encode or check event contents in order to avoid cross-site scripting issues.

Securing Connections to Data Sources

You can create custom health-monitoring event providers to log event data to a database. ASP.NET includes a SQL provider. For more information about how to log event data, see Securing Data Access.

To help secure the connection to the database server, you should encrypt connection-string information in the configuration file by using protected configuration. For more information, see Encrypting Configuration Information Using Protected Configuration.

When you use a SQL provider, you must secure the database appropriately by using authentication. Microsoft SQL Server Express Edition files must be secured by using access control lists (ACLs) and SQL authentication.

Securing Against Denial-of-service Attacks

Web events can be triggered by an HTTP request or by application code that generates exceptions or events. Event-provider capacity can be exceeded by a high volume of events, or by large events. In that case, the ASP.NET application or server can be overwhelmed, which might affect memory usage, disk space, and network traffic.

To reduce an application's exposure to a denial-of-service attack, by default ASP.NET uses the following design:

• ASP.NET measures out one instance of an event per minute. This throttling frequency is configured in the profiles element and is associated with events and providers in the rules element.

• Event buffering is isolated for each provider type to prevent competition for buffer space. Buffer settings are configured in the bufferModes element. Providers can be configured to use a specific set of buffer settings by specifying the bufferModes element that contains the appropriate settings.

• To raise a custom event, medium trust or higher is required.

As a system administrator, you can configure throttling and buffering settings to avoid overflow, especially for events that can be triggered by HTTP requests. Additionally, you can set up separate buffer modes to deal with important and unimportant events.

Security for Error Messages and Events

To prevent sensitive information from being exposed to unwanted sources, configure your application not to display detailed error messages. You can also configure the application to display detailed error messages only when the client is the Web server itself. For more information, see customErrors.

By default, ASP.NET logs high-volume, exceptional, per-request Web events to the performance monitoring system. In the default configuration, this means that failed login attempts will record user names and other diagnostic information in the Application event log. This data can be viewed in the Windows Event Viewer. If the server is running one of the Microsoft Windows Server products, you can improve the security of the application by securing the event log. You can also set parameters to specify size, retention, and other characteristics of the event log to prevent an indirect denial-of-service attack against it.

Locking ASP.NET Health Monitoring Configuration

In application hosting scenarios, you often want to lock some settings on a site to prevent modification. For example, you might want to lock the health monitoring settings for hosted applications to reduce the risk of accidental modifications to the Web application's configuration.

You can lock configuration settings by adding an allowOverride="false" attribute in a <location> tag. This causes the configuration system to throw an error if a configuration file that is lower in the hierarchy tries to override any configuration section that is defined in the location element.

The following example configuration file shows how to lock the healthMonitoring section of an ASP.NET application that is named application1. The settings could be stored at either the server level (in the machine.config file) or at the site level.

<configuration>
  <location path="application1" allowOverride="false">
    <system.web>
      <healthMonitoring
        enabled="true"
        heartBeatInterval="60">
        <bufferModes>
          <add name="Logging"
            maxBufferSize="1000"
            maxFlushSize="200"
            urgentFlushThreshold="800"
            regularFlushInterval="00:30:00"
            urgentFlushInterval="00:05:00"
            maxBufferThreads="1"
          />
        </bufferModes>
        <providers>
           <add name="EventLogProvider"
            type="System.Web.Management.EventLogWebEventProvider, System.Web, Version=%ASSEMBLY_VERSION%, Culture=neutral, PublicKeyToken=%MICROSOFT_PUBLICKEY%"
            buffer="true"
            bufferMode="Logging"
          />
        </providers>
        <eventMappings>
          <add name="All Errors"
            type="System.Web.Management.WebBaseErrorEvent, System.Web, Version=%ASSEMBLY_VERSION%, Culture=neutral, PublicKeyToken=%MICROSOFT_PUBLICKEY%" 
          />
        </eventMappings>
        <profiles>
          <add name="Default"
            minInstances="1"
            maxLimit="Infinite"
            minInterval="00:10:00"
          />
        </profiles>
        <rules>
          <add name="All Errors Default"
            eventName="All Errors"
            provider="EventLogProvider"
            profile="Default"
            minInterval="00:01:00" 
          />
        </rules>
      </healthMonitoring>
    </system.web>
  </location>
</configuration>

You can lock elements with more granularity by using additional attributes such as lockItem, lockAttributes, and lockElements. For more information, see General Attributes Inherited by Section Elements.

Back to top

Code Examples

How to: Implement and Raise Custom ASP.NET Health Monitoring Events

How to: Implement the Health Monitoring Custom Provider Example

How to: Send E-mail for Health Monitoring Notifications.

Walkthrough: Listening for WMI Events in ASP.NET Health Monitoring

Back to top

Class Reference

• System.Web.Management
  The namespace that contains types for managing and monitoring the health status of Web applications.

• System.Management
  The namespace that contains types for connecting to the Windows Management Instrumentation (WMI) infrastructure.

• System.Management.Instrumentation
  The namespace that contains types to instrument applications for WMI potential consumers.

• HealthMonitoringSection
  The type that programmatically gets or sets the healthMonitoring configuration attributes.

Back to top

See Also

Tasks

How to: Lock ASP.NET Configuration Settings

Concepts

Extending ASP.NET Health Monitoring Events

ASP.NET Configuration Overview

Reference

bufferModes Element for healthMonitoring (ASP.NET Settings Schema)

providers Element for healthMonitoring (ASP.NET Settings Schema)