Using ASP.NET Health Monitoring Events

Article
10/15/2014

There are two approaches you can follow when using the ASP.NET health monitoring events:

Use built-in Web event and provider classes. You will not usually need 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 need to configure them as explained elsewhere. For more information, see How to: Send E-mail for Health Monitoring Notifications.
Create custom classes for either Web events or providers, or both. You typically create custom Web events if you need to 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.

For additional information on custom health monitoring events, search for "health monitoring" in the MSDN Library.

Using Built-in Web Events and Providers

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

Add the built-in ASP.NET Web event class 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 defined in the eventMappings element. For a list of these classes, see the section "Web Events" in ASP.NET Health Monitoring Overview.
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 event providers.
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.
Parameter values for the configured items are specified, such as those that limit the number of events that can occur, specify the interval between two events, or specify event buffering options for the SQL and mail providers.

The following code example shows the default configuration for built-in health monitoring classes in the root Web.config file:

<healthMonitoring heartbeatInterval="0" enabled="true">
  <bufferModes>
    <add name="Critical Notification" 
      maxBufferSize="100" 
      maxFlushSize="20" 
      urgentFlushThreshold="1" 
      regularFlushInterval="Infinite" 
      urgentFlushInterval="00:01:00" 
      maxBufferThreads="1" />
    <add name="Notification" 
      maxBufferSize="300" 
      maxFlushSize="20" 
      urgentFlushThreshold="1" 
      regularFlushInterval="Infinite" 
      urgentFlushInterval="00:01:00" 
      maxBufferThreads="1" />
    <add name="Analysis" 
      maxBufferSize="1000" 
      maxFlushSize="100" 
      urgentFlushThreshold="100" 
      regularFlushInterval="00:05:00" 
      urgentFlushInterval="00:01:00" 
      maxBufferThreads="1" />
    <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=2.0.0.0,Culture=neutral,
       PublicKeyToken=b03f5f7f11d50a3a" />
    <add 
      ConnectionStringName="LocalSqlServer" 
      maxEventDetailsLength="1073741823" 
      buffer="false" 
      bufferMode="Notification" 
      name="SqlWebEventProvider"
      type="System.Web.Management.SqlWebEventProvider,
        System.Web,Version=2.0.0.0,Culture=neutral,
        PublicKeyToken=b03f5f7f11d50a3a" />
    <add 
      name="WmiWebEventProvider"
      type="System.Web.Management.WmiWebEventProvider,
       System.Web,Version=2.0.0.0,Culture=neutral,
       PublicKeyToken=b03f5f7f11d50a3a" />
  </providers>

  <profiles>
    <add 
      name="Default" 
      minInstances="1" 
      maxLimit="Infinite" 
      minInterval="00:01:00" 
      custom="" />
    <add 
      name="Critical" 
      minInstances="1" 
      maxLimit="Infinite" 
      minInterval="00:00:00" 
      custom="" />
  </profiles>

  <rules>
    <add 
      name="All Errors Default" 
      eventName="All Errors" provider="EventLogProvider" 
      profile="Default" 
      minInstances="1" 
      maxLimit="Infinite" 
      minInterval="00:01:00" 
      custom="" />
    <add 
      name="Failure Audits Default" 
      eventName="Failure Audits"
      provider="EventLogProvider" 
      profile="Default" 
      minInstances="1" 
      maxLimit="Infinite" 
      minInterval="00:01:00"
      custom="" />
  </rules>

  <eventMappings>
    <add 
      name="All Events" 
      type="System.Web.Management.WebBaseEvent, 
      System.Web,Version=2.0.0.0,Culture=neutral,
        PublicKeyToken=b03f5f7f11d50a3a" 
      startEventCode="0"
      endEventCode="2147483647" />
    <add 
      name="Heartbeats" 
      type="System.Web.Management.WebHeartbeatEvent, 
System.Web,Version=2.0.0.0,Culture=neutral,
      PublicKeyToken=b03f5f7f11d50a3a" 
      startEventCode="0" 
      endEventCode="2147483647" />
    <add 
      name="Application Lifetime Events" 
      type="System.Web.Management.WebApplicationLifetimeEvent, 
      System.Web,Version=2.0.0.0,Culture=neutral, 
      PublicKeyToken=b03f5f7f11d50a3a" 
      startEventCode="0" 
      endEventCode="2147483647" />
    <add 
      name="Request Processing Events" 
      type="System.Web.Management.WebRequestEvent, 
System.Web,Version=2.0.0.0,Culture=neutral, 
        PublicKeyToken=b03f5f7f11d50a3a" 
      startEventCode="0" 
      endEventCode="2147483647" />
    <add 
      name="All Errors"
      type="System.Web.Management.WebBaseErrorEvent, 
      System.Web,Version=2.0.0.0,Culture=neutral, 
        PublicKeyToken=b03f5f7f11d50a3a" 
      startEventCode="0" 
      endEventCode="2147483647" />
    <add 
      name="Infrastructure Errors" 
      type="System.Web.Management.WebErrorEvent, 
        System.Web,Version=2.0.0.0,Culture=neutral, 
        PublicKeyToken=b03f5f7f11d50a3a" 
      startEventCode="0" 
      endEventCode="2147483647" />
    <add 
      name="Request Processing Errors" 
      type="System.Web.Management.WebRequestErrorEvent, 
        System.Web,Version=2.0.0.0,Culture=neutral, 
        PublicKeyToken=b03f5f7f11d50a3a" 
      startEventCode="0" 
      endEventCode="2147483647" />
    <add 
      name="All Audits"
      type="System.Web.Management.WebAuditEvent, 
        System.Web,Version=2.0.0.0,Culture=neutral, 
        PublicKeyToken=b03f5f7f11d50a3a" 
      startEventCode="0" endEventCode="2147483647" />
    <add 
      name="Failure Audits" 
      type="System.Web.Management.WebFailureAuditEvent, System.Web,Version=2.0.0.0,
        Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" 
      startEventCode="0" 
      endEventCode="2147483647" />
    <add 
      name="Success Audits" 
      type="System.Web.Management.WebSuccessAuditEvent, 
        System.Web,Version=2.0.0.0,Culture=neutral, 
        PublicKeyToken=b03f5f7f11d50a3a" 
      startEventCode="0" 
      endEventCode="2147483647" />
  </eventMappings>
</healthMonitoring>

Configuring a Custom Provider

If you require custom processing of Web event information, you can build your own custom health event provider. You can implement a custom event provider by creating 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 and 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 containing 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 code example, where the Version and PublicKeyToken match your assembly:
```
type="Microsoft.Samples.Web.Management.SampleCustomEventProvider, Sample.SampleCustomEventProvider,Version=n.n.n.n,Culture=neutral, PublicKeyToken=xxxx"
```

The following code example associates 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 not only that you modify the configuration file but also that the custom event be explicitly raised at the proper time.

For information on the appropriate time to raise an event and have it contain data, use the Web Event Information table in Extending ASP.NET Health Monitoring.

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 containing the custom Web event implementation to the Bin subdirectory of the ASP.NET application or 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 need to specify only the class name.

The following code example associates 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>

Using ASP.NET Health Monitoring Events

Using Built-in Web Events and Providers

Configuring a Custom Provider

Configuring a Custom Event

See Also

Tasks

Reference

Concepts

Other Resources

Additional resources