Monitoring Your Application[3]->Web Events

The web events feature provides a general framework for emitting runtime events to indicate the occurrence of interesting actions in the application, report application health, or any other information of interest. The feature allows administrators to determine exactly which events they are interested in via event subscriptions in configuration, and specify channels through which the events are delivered. The feature includes several channel providers out of the box that cater to a variety of scenarios:

• Saving events to Microsoft™ SQL Server
• Sending event reports through email
• Writing events to the Windows™ Event Log
• Forwarding events through WMI

ASP.NET 2.0 itself uses the web event feature to provide health reporting, auditing, and instrumentation of various pieces of runtime functionality. Anyone can develop and raise custom event types to further instrument their application.

In the example below, the application is configured to send all emitted web events to the SQL Server provider. The page raises an instance of the custom event type deriving from WebEventBase when it loads, and uses a data source control to read the events directly out of the SQL Server event table. The GridView displaying the list of events also shows some of the events that ASP.NET itself generates during the request processing cycle.

C# Health Monitoring Events

Events and Event Providers

Web events are instances of various web event base classes constructed at runtime with the appropriate information, and assigned an event code / details code that can be used to identify the condition that the event is intended to represent. ASP.NET has a set of base classes it uses to instrument a number of conditions arising in the infrastructure, and allows the application to extend the base classes with custom event classes that represent arbitrary information the application chooses to report. These custom events can then be created and raised by the application code through the Web event engine.

ASP.NET includes the following web event base classes (among others), residing in the System.Web.Management namespace:

Feature	Description
WebBaseEvent	The base event class for all events. Contains the required properties for all events, such as event code, event detail code, date and time when the event was raised, sequence number, the event message, and event details.
WebManagementEvent	The base event class for management events, such as application lifetime, request, error, and audit events.
WebHeartbeatEvent	The event that is generated by the application in regular intervals to capture useful runtime state information.
WebAuditEvent	The base class for security audit events, that are used to mark conditions such as authorization failure, decryption failure, etc.
WebRequestEvent	The base class for all informational request events.
WebBaseErrorEvent	The base class for all events indicating error conditions.

When events are raised, they are processed by the Web Event engine, which routes them to one or more Web Event providers that represent event consumers configured to listen for specific events in the Health Monitoring configuration. The Web Event engine also provides a number of other services, such as throttling events to avoid intolerable volumes.

A provider in the world of Web Events is essentially the pluggable consumer of events. ASP.NET 2.0 provides several built in providers that you can use out of the box, and also gives you the ability to implement and configure your own custom providers. Included providers can output events to Microsoft SQL Server database, Windows EventLog, WMI namespace, or email.

Configuring Events

NOTE: In this section, all of the configuration refers to elements inside the section unless otherwise specified.

In order to receive events, a subscription needs to be created that maps an event set to an event consumer, implemented by a Web Event provider. This subscription has the following parts:

Event Mapping. This defines a set of events and the name by which they can be referred to in subscriptions, identifying the event set by the event base class that all of the events in this set must derive from and an optional event code range. For example, the following mapping creates an event set including all audit events with event codes from 0 to 1000:

<eventMappings>
<add name="Audit Events" startEventCode="0" endEventCode="1000" type="System.Web.Management.WebAuditEvent" />
</eventMappings>

Event Subscription Rule. This defines the mapping between the event set and the Web Event provider that will process it. The rule can also optionally specify a profile containing event throttling information to restrict the amount of events processed by the rule, or specify these settings directly.

For example, the following rule channels the Audit Events event set we created above to the default EventLog provider that is installed with ASP.NET 2.0:

<rules>
<add name="MyFirstSubscription" eventName="Audit Events" provider="EventLogProvider" />
</rules>

Provider. This defines the provider of the event channel that will consume the events. Here you can either configure one of the default providers that ASP.NET 2.0 includes, or specify your own type that derives from the Web Event provider base class.

For example, the below configuration exists by default in the ASP.NET 2.0 installation in order to enable the ASP.NET Event Log provider to write events to the Windows Event Log:

<providers>
<add name="EventLogProvider" type="System.Web.Management.EventLogWebEventProvider" />
</providers>

You can also configure other settings to further control the behavior of Web Events inside the section, such as setting up profiles for throttling settings applied to rules, and buffering modes for buffered providers.

Creating a Custom Event

In order to create a custom event type, you have to derive your own event class from one of the derivable Web Event base classes. You can then create and raise instances of this event at runtime, and configure subscriptions to it as described above.

In the example below, a custom event is created with a custom event code and message and an instance of this event is raised in a page event handler:

// in the code directory, or your application source code
class MySampleEvent : System.Web.Management.WebBaseEvent
{
public const int MySampleEventCode = 200001;
public MySampleEvent(String message) : base(message, null, MySampleEventCode) {}
}
// in an aspx page
void Page_Load()
{
// create an instance of the event
MySampleEvent e = new MySampleEvent("In Page_Load()");
// raise the event to the web event engine
e.Raise();
}

Instrumenting Your Application

In order to instrument your application for runtime monitoring, you should create custom event classes that derive from the proper web event base classes, and contain additional information that is interesting for your application. You can then create and raise instances of these events in code that you would like to instrument.

After creating and raising your own events inside your application or its components, you can configure event subscriptions to channel the particular events of interest to the appropriate providers.

Throttling Events

Event throttling refers to constraining the rate at which events are passed to providers to avoid overwhelming the provider, or the output means that it uses to transport, process, store or display events. Throttling settings are applied at rule level.

You can throttle events by specifying throttling settings on a per rule basis, or creating a profile that defines a set of throttling settings. The throttling abilities you have at your disposal include the ability to only log a single event for N event occurrences, a single event in a given time period, or only the first N occurrences of a given event.

In the example below, the auditing event subscription rule is modified to guarantee the maximum event rate to be 1 event / second:

<rules>
<add name="MyFirstSubscription" eventName="Audit Events" provider="EventLogProvider" minInterval="00:00:01" />
</rules>

NOTE: Throttling loses events, so be careful when setting throttling settings for sensitive events such as auditing events. An alternative to throttling is using the buffering capabilities of a particular provider, which attempts to avoid losing events at the expense of delaying their delivery.

In the below example, the throttling setting is placed in a profile that can then be shared between multiple rules:

<profiles>
<add name="MyProfile" ="00:00:01" />
</profiles>
<rules>
<add name="MyFirstSubscription" eventName="Audit Events" provider="EventLogProvider" profile="MyProfile" />
</rules>