Extending ASP.NET Health Monitoring Events

You can perform the following tasks to extend ASP.NET health monitoring features.

• Create a custom Web event class by inheriting from the standard Web event types. Note that if your application inherits from WebBaseEvent or WebBaseErrorEvent it must run in partial trust. For all other events it must run in full trust. To add custom data to a custom event, override the FormatCustomEventDetails method. Do not override the ToString method. This is to avoid overwriting or tampering with sensitive system information. Custom events must be explicitly raised by calling the Raise method. (Standard events can be raised only by ASP.NET.) For code examples, see How to: Implement and Raise Custom ASP.NET Health Monitoring Events.

• Customize a standard event type by creating a class that implements the IWebEventCustomEvaluator interface.

• Create a custom provider to process an event by creating a class that inherits the WebEventProvider or BufferedWebEventProvider class. If your provider performs logging, you can also use the WebEventFormatter class. 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 code examples, see How to: Implement the Health Monitoring Custom Provider Example.

Buffering ASP.NET Health Monitoring Events

You can configure the SQL and mail health monitoring event providers (SqlWebEventProvider, SimpleMailWebEventProvider, and TemplatedMailWebEventProvider) to use event buffering. This helps reduce the effect on application performance of sending frequent e-mail messages or performing frequent SQL server insertions. By buffering health monitoring events, you also protect the SMTP server and SQL Server from heavy loads that can be caused by high event volume.

SQL Event Provider Buffering

If you enable buffering for the SQL event provider, the provider buffers event information according to the specified buffer mode before it inserts the event information into the database in a batch.

By default, the SqlWebEventProvider provider is not configured to use buffering. Every time that an event is raised, its information is immediately inserted into the database. You can override this default setting by enabling buffering in the providers element of the Web.config file where the SQL provider is specified. You do so by setting the buffer attribute of the add element to true. If you configure your own SQL provider (that is, if you do not use SqlWebEventProvider), and if you do not specify a value for the buffer attribute, the default is true.

You can customize buffering behavior by selecting a predefined buffering mode. Alternatively, you can add custom elements to the bufferModes collection. Each element defines properties such as the size of the buffer and the frequency for flushing the buffer. You can then configure the provider to use one of the buffer modes you have defined.

The example that follows shows the configuration settings for the SQL event provider with buffering enabled.

Note

The Analysis bufferModes element is already configured in the root Web.config file and does not have to be declared again in an application-level Web.config file. The SqlWebEventProvider providers element is also configured in the root Web.config file, but the buffer attribute is set to false and the bufferMode attribute is set to Notification. Therefore the providers element that is shown in the example must be declared in an application-level Web.config file. You must also use a clear or remove element to remove the higher-level configuration for the SqlWebEventProvider provider.

In the example, the SQL event provider is configured to use the Analysis buffer mode when buffering is enabled, which is defined in the bufferModes element. In this mode, the provider flushes the event information every 5 minutes. It flushes up to 100 events per notification, and buffers up to 1000 events in case of a sudden increase in the frequency of events. The provider guarantees not to send events more often then one time every minute.

<healthMonitoring>
  <providers>
    <clear/>
    <add 
      ConnectionStringName="LocalSqlServer" 
      maxEventDetailsLength="1073741823"
      buffer="true" 
      bufferMode="Analysis" 
      name="SqlWebEventProvider"
      type="System.Web.Management.SqlWebEventProvider,System.Web, Version=2.0.0.0,Culture=neutral,PublicKeyToken=b03f5f7f11d50a3a" 
    />
  </providers>
  <bufferModes>
    <add 
      name="Analysis" 
      maxBufferSize="1000" 
      maxFlushSize="100"
      urgentFlushThreshold="100" 
      regularFlushInterval="00:05:00"
      urgentFlushInterval="00:01:00" 
      maxBufferThreads="1"
    />
  </bufferModes>
</healthMonitoring>

E-mail Event Provider Buffering

If you enable buffering for the e-mail event providers, the providers buffer events before they send e-mail messages as event notifications. If you configure an e-mail event provider and you do not specify a value for the buffer attribute of the add element for the e-mail event provider, the default is true. You can disable buffering by setting the buffer attribute to false.

You can customize buffering behavior by selecting a predefined buffering mode. Alternatively, you can add custom elements to the bufferModes collection. Each element defines properties such as the size of the buffer and the frequency for flushing the buffer. You can then configure the provider to use one of the buffer modes you have defined. It is recommended that you use the CriticalNotification mode.

The following example shows the configuration settings for the e-mail event providers with buffering disabled for the SimpleMailWebEventProvider class and enabled for the TemplatedMailWebEventProvider class. The TemplatedMailWebEventProvider provider is configured to use the CriticalNotification buffer mode, which is already configured in the root Web.config file. In CriticalNotification mode, the provider attempts to flush all event information as soon as events are received. However, the flush attempt will not succeed more frequently than every minute in order to avoid putting a heavy load on the e-mail server. The messages are of manageable size. The information is for 20 events at most.

If the health monitoring system receives more event information than the maximum permitted, the oldest events are dropped when new events are generated. The health monitoring system tries to avoid dropping events by flushing more frequently when the buffer is getting full. However, it will not attempt to send any information for events if they have been dropped. (However, it does include notification in the next flush that events were dropped.) Newer events will be delayed at most five minutes if the provider is under heavy load, assuming they are not dropped because of a full buffer.

<healthMonitoring>
  <providers>
    <!-- mail provider with attributes that are always relevant -->
    <add 
      name="SimpleMailWebEventProvider" 
      type="System.Web.Management.SimpleMailWebEventProvider"
      to="SystemAdministrator@contoso.com"
      from="HealthMonitoring@contoso.com"
      buffer="false" 
    />
    <!-- mail provider with attributes that are relevant only 
         when buffering is enabled -->
    <add 
      name="SampleTemplatedMailWebEventProvider" 
      type="System.Web.Management.TemplatedMailWebEventProvider"
      to="SystemAdministrator@contoso.com" 
      from="HealthMonitoring@contoso.com" 
      buffer="true" 
      bufferMode="Critical Notification"
      template="Template.aspx" />
  </providers>
  <bufferModes>
    <add 
      name="Critical Notification" 
      maxBufferSize="100" maxFlushSize="20"
      urgentFlushThreshold="1" 
      regularFlushInterval="Infinite" 
      urgentFlushInterval="00:01:00"
      maxBufferThreads="1"
    />
  </bufferModes> 
</healthMonitoring>

For the example to work, you must configure an SMTP server in the configuration file as shown in the following example.

<system.net>
  <mailSettings>
    <smtp deliveryMethod="Network">
      <network 
        defaultCredentials="true" 
        host="127.0.0.1" 
        port="25" 
        username="username" 
        password="password" />
    </smtp>
  </mailSettings>
</system.net>

For more information, see <mailSettings> Element (Network Settings).

Note

There are security risks associated with storing clear-text passwords in a configuration file. If you keep credentials in the configuration file, you should encrypt the contents of the <mailSettings> configuration element by using protected configuration. For more information, see Encrypting Configuration Information Using Protected Configuration.

Buffer Mode Settings

You can set the following attributes of the add element in the bufferModes element to specify buffer behavior:

• regularFlushInterval   The regular event information flush interval.

• urgentFlushThreshold   The number of events whose information should be buffered before the buffer is flushed.

The following settings specify the guarantees made by the provider to the event receiver.

• maxBufferSize   The maximum number of events whose information the buffer will hold. If the number of events in the buffer would exceed this value, older events are dropped.

• maxFlushSize   The maximum number of events whose information the provider will flush at a time.

• urgentFlushInterval   The minimum time that the provider will wait before it performs another urgent flush. If the time represented by the urgentFlushInterval property has not passed since the last flush but the buffer is full, information from older events is discarded from the buffer. The provider keeps track of how many events were discarded, and includes a warning in the next event notification.

Using WMI to Track ASP.NET Health Monitoring Events

One way to monitor the ASP.NET health events is to use the Windows Management Instrumentation (WMI) event provider, the WmiWebEventProvider class. This provider converts Web health monitoring events (Web events) to WMI events. WMI provides a standard object model in which the entities you want to monitor can be represented as objects. These entities represent computers, network cards, printers, software applications, and so on. The entities are mapped into the WMI object model so that they can be monitored by custom applications. The following illustration shows the relationship between the ASP.NET Web events, WMI, and a consumer application that listens for WMI events.

Relationship between ASP.NET and WMI

Connection Between Health Events and WMI

ASP.NET health monitoring provides the infrastructure for the connection between health events and WMI. It does so by mapping these events into the WMI classes so that they can be treated as WMI objects. It also provides the support to process the health events and dispatch them to the WMI system. For details about how to map ASP.NET events to WMI, see Walkthrough: Listening for WMI Events in ASP.NET Health Monitoring. For more information about WMI, see Windows Management Instrumentation on the MSDN Web site.

The following list describes the steps that are required to monitor health events with WMI:

1. Define the mapping between the Web event classes and WMI objects. This step is already done for you for each standard Web event class. These mappings are contained in the Managed Object Format (MOF) file for ASP.NET, %SystemRoot%\Microsoft.NET\Framework\<version>\aspnet.mof file.

   Note

   All custom events are mapped to the base event type in WMI. It is not possible to map a custom ASP.NET health monitoring event to an arbitrary WMI event.

   For example, the following code shows the definition of the WMI class mapped to the WebHeartbeatEvent type.

   class HeartbeatEvent : ManagementEvent {
       /*
        * ProcessStatistics    
        */
       DATETIME    ProcessStartTime;
       sint32      ThreadCount;
       sint64      WorkingSet;
       sint64      PeakWorkingSet;
       sint64      ManagedHeapSize;
       sint32      AppdomainCount;    
       sint32      RequestsExecuting;
       sint32      RequestsQueued;
       sint32      RequestsRejected;
   }; 
   

   For more information about MOF files, see Managed Object Format in the WMI SDK in MSDN.

2. Define an ASP.NET health monitoring provider that will process the events.

   The standard provider is the WmiWebEventProvider class. By default, this is already configured in the healthMonitoring section of the root Web.config file by using the following element:

   <providers>
     <add 
       name="WmiWebEventProvider" 
       type="System.Web.Management.WmiWebEventProvider,System.Web, Version=2.0.0.0,Culture=neutral,PublicKeyToken=b03f5f7f11d50a3a" 
     />
   </providers>
   

3. Enter the appropriate settings in the healthMonitoring section of the configuration file to create the association between Web event classes and the WMI event provider, the WmiWebEventProvider class.

   By default, the WMI event provider subscribes to no Web events. You can use the following elements in an application-level Web.config file to subscribe the WMI event provider to all Web events. By default, the All Events event type is configured in the eventMappings element in the root Web.config file. It is mapped to the WebBaseEvent class.

   <rules>
     <add 
       name="Testing Wmi"
       eventName="All Events" 
       provider="WmiWebEventProvider" 
       profile="Critical"
     />
   </rules>
   

4. Create an application to listen for WMI events, or use a third-party application.

   The code example in Walkthrough: Listening for WMI Events in ASP.NET Health Monitoring creates a console application that displays event information whenever a Web event is raised.

Customizing the WMI Health Events Infrastructure

When a Web event occurs, ASP.NET health monitoring dispatches it to the WmiWebEventProvider object. The provider object processes the event and fills in the appropriate data according to the related MOF class definition. The provider then dispatches this data to the WMI system by using a call to unmanaged code.

The only customization option for sending Web events to WMI is if you create a custom application that consumes ASP.NET health monitoring events after they have been issued as WMI events. In that case, the only configuration change you have to make is to configure a new rules element as listed previously. Your application will listen for the ASP.NET health events in the form of WMI events, as issued by the operating system. For more information, see Walkthrough: Listening for WMI Events in ASP.NET Health Monitoring.

Note

You cannot extend the WmiWebEventProvider class. The only event provider classes that you can extend are the WebEventProvider and BufferedWebEventProvider classes.

Implementing Custom ASP.NET Health Monitoring Events and Providers

By default, some events are already captured in performance counters, captured in the event log, or sent to the ASP.NET tracing system. You can enable other events by mapping them to existing providers. For more information, see the "Consuming Web Events Using Event Providers" section in ASP.NET Health Monitoring Overview.

If no existing Web event or provider class meets your needs, you can extend these classes. The following table lists ways that you can customize ASP.NET health monitoring.

Task	Implementation	Example
Create a custom Web event class.	Create a class that inherits from the WebBaseEvent and implements the Raise virtual method. To add custom data to a custom event, override the FormatCustomEventDetails method.	How to: Implement and Raise Custom ASP.NET Health Monitoring Events
Create a custom event provider to process a built-in or custom Web event.	Create a class that inherits from the WebEventProvider class (or one of the derived classes). If your provider performs logging, also inherit from the WebEventFormatter class.	How to: Implement the Health Monitoring Custom Provider Example

See Also

Tasks

How to: Lock ASP.NET Configuration Settings

Reference

bufferModes Element for healthMonitoring (ASP.NET Settings Schema)

providers Element for healthMonitoring (ASP.NET Settings Schema)

Concepts

ASP.NET Health Monitoring Overview

ASP.NET Configuration Overview