Creating New Subscribers for Intercept Studio SE-Viewer

Description

SE-Viewer allows you to transfer incoming event information to external resources. This can be done using subscribers - special classes through which SE-Viewer sends information about events in compliance with defined notification rules. Notification rules are defined through the 'Notification Management Wizard' in SE-Viewer. See the 'Intercept Studio User's Manual' for more information.

This document includes an example of creating a flat-file subscriber (see 'Sample Code - FileSubscriber.cs'). Examples given within this document will refer to this sample code.

Interfaces

The Interfaces that a subscriber should implement are described below. The Subscriber class must extend these specific interfaces for integration, which are defined in the ISubscriber.dll library. ISubscriber.dll can be located in [drive]:\ \Program Files\AVIcode\Intercept\SEViewer\Subscribers.

ISubscriberConstruction

Each subscriber must implement this interface. It allows the initialization of the subscriber object after creation and before sending a notification.

The subscriber is initialized with a string that contains an xml node with settings. If the subscriber does not need any initialization, then this xml node contains no child nodes (<settings/>). See section 'Deployment and configuration' for more details about subscriber initialization.

namespace AVIcode.Intercept.SEManager.Subscriber

{

/// <summary>

/// Allows initializing the class (for SE-Viewer 2.0)

/// </summary>

public interface ISubscriberConstruction

{

/// <summary>

/// Initialize class

/// </summary>

/// <param name='settings'>Settings from config in the XML format</param>

void Init(string settings);

}

[...]

}

Isubscriber

The Isubscriber interface must be implemented because SE-Viewer uses it to send events to the subscriber.

Namespace AVIcode.Intercept.SEManager.Subscriber

{

[...]

/// <summary>

/// Interface for sending events without configuration (for SE-Viewer 2.0)

/// </summary>

public interface Isubscriber

{

/// <summary>

/// Send event based on the Event parameters

/// </summary>

void LogEvent(

string url

, long eventID

, bool newGroup

, long eventGroupID

, string eventClass

, string eventClassVersion

, string eventClassName

, string eventClassType

, EventType eventType

, System.Collections.Hashtable eventProperties

);

}

[...]

}

The LogEvent method uses a number of parameters. Here is short description of each of them:

url - A link that will connect directly to this event page in SE-Viewer
eventID - A unique numerical identifier for this event in SE-Viewer
newGroup - The new group flag will be marked as 'True' if this is the first event in a consolidated group
eventGroupID - The event group ID is the unique numerical identifier for a consolidated group
eventClass - The event class name is an Intercept internal name for the event class
eventClassVersion - The event class version is an Intercept internal version number for the event class
eventClassType - Type of the event (performance or exception)
eventType - The event type for a performance event is 'information', and the Event Type for an exception event is 'error'
eventProperties - A hashtable object that contains special properties:

eventProperties
Name	Type	Description
'machineName'	String	The 'Machine Name' is the name of the monitored computer (from which the Intercept Agent generated an event)
Source	String	The Source is the name of the web application from which Intercept Studio received the event
'utcOffset'	Int32	The UTC offset between the monitored server and UTC time
'timeZoneName'	String	The name of the time zone (e.g. Eastern Standard)
'utcEventDate'	DateTime	The UTC Event Date is the time that the event occurred is reported in Coordinated Universal (UTC) time (five hours ahead of Eastern Standard Time) since the sender and recipient may be in different time zones
'category'	String	The 'Category' field is included for compatibility with the Microsoft Event Log. For exception events, it displays the exception class, but it unused for performance events
'eventCode'	String	The 'Event Code' field is included for compatibility with the Microsoft Event Log. For exception events, it displays the exception class, but it unused for performance events
'description'	String	The description of the event
'eventDuration'	Int64	Duration of the performance event
'component'	String	The component name
'componentVersion'	String	The version of the component
'user'	String	The user name
Name	String	The name of the root node is the location where the exception was raised, which provides information about entry points (external call) for applications: Asp page, Webservice method, Remoting methods, etc
'appType'	String	Application type (Remoting, Web services etc.)
'isTestMessage'	Boolean	The flag that indicates that message is for test purposes and the subscriber should not use other properties, because they are unused and may be null
'messageFormat' **	String	The type of the additional information about event (html, text). This properties appear when attribute with the same name exists in the appropriate 'subscriber' tag in the SEViewer.config
'messageBody' **	String	The additional information about the event in the format specified by the 'messageFormat' field. It is defined only when the 'messageFormat' property is set.
Aspect	String	Aspects are case sensitive, and may be any of the following values: 'applicationfailure', 'connectivity', 'security', 'performance', 'uncategorized', 'systemfailure'. The 'uncategorized' value is used to represent 'Operational Info'.

Functionality

Subscribers may be used in several different ways. These interactions between SE-Viewer and subscribers are described below.

Automatic notifications

This scenario is used for the automatic sending of event notifications from SE-Viewer using the configured notification rules. These steps will be taken for sending events for each notification rule:

The subscriber object is created using the settings in the SEViewer.config file (see 'Deployment and configuration' below)
SE-Viewer calls the Init method of the ISubscriberConstruction interface with the settings that were stored for the current rule
SE-Viewer calls the LogEvent method of the ISubscriber interface with all of the parameters about the event
If the subscriber implements the IDisposable interface then SE-Viewer will call the Dispose method for cleaning up the resources

Sending a test notification from the Notification Management Wizard in SE-Viewer

A test notification can be sent from the Notification Management Wizard when creating or modifying a notification rule. The following actions are taken after user presses Send test notification :

SE-Viewer creates a subscriber object using the settings from the SEViewer.config file (see 'Deployment and configuration' below)
SE-Viewer calls the Init method of the subscriber passing it settings that are currently typed into the Notification Management Wizard form
SE-Viewer calls the LogEvent method. During a test notification (when the eventProperties Hashtable property isTestMessage = True) most of the LogEvent properties are set to null.
If the subscriber implements the IDisposable interface then SE-Viewer will call the Dispose method for cleaning up the resources

Sending notifications via Send to... and the Send Wizard

Sending notification about event via 'Send to...' (described in the Intercept Studio User's Manual) is available only when the IWebSubscriber interface is implemented.

namespace AVIcode.Intercept.SEManager.Subscriber

{

[...]

/// <summary>

/// Interface to configure and send events from Web (for SE-Viewer 2.0)

/// </summary>

public interface IWebSubscriber

{

/// <summary>

/// Prepares HTML for displaying to user

/// </summary>

// Form must not contain submit button or other postback actions

// GetForm should return HTML body that will be used as content of the html <form>

string GetForm(

string mode

,string url

, long eventID

, bool newGroup

, long eventGroupID

, string eventClass

, string eventClassVersion

, string eventClassName

, string eventClassType

, EventType eventType

, System.Collections.Hashtable eventProperties

, System.Collections.Specialized.NameValueCollection defaultValues

);

/// <summary>

/// Send event based on the Event and Web form result

/// Function raises SubscriberException class, which is used for logical exceptions in

/// subscribers, validation error by example.

/// </summary>

void SendEvent(

string mode ,

System.Collections.Specialized.NameValueCollection formResult

);

}

Contact AVIcode for additional information regarding the IWebSubscriber interface.

Deployment and configuration

To add a new subscriber to SE-Viewer you need to do the following:

Copy your subscriber library (dll) to:

[drive]:\Program Files\AVIcode\Intercept\SEViewer\Subscribers

Open [drive]:\Program Files\AVIcode\Intercept\SEViewer\SEViewer.config
Add a new <subscriber> subsection to the <subscribers> section of SE-Viewer configuration file.
Add an optional attribute 'messageFormat' to receive additional information about event; possible values: Text, html.
Set the <subscriber class> attribute to a string that will be displayed in the available notification types. SE-Viewer will use class when working with the notification rules. The subscriber class must have unique value and may not be modified later.
Set <assemblyName> tag to the name of the assembly where the subscriber class is defined.
Set <class> tag to the full namespace of the subscriber.
The <settings> node should contain xml with common (template) configuration settings for the subscriber. It will be used during creation the subscriber, and the user will be able to modify settings. If the <settings> node does not contain any child nodes then the user will not be able to modify the settings and that subscriber does not need to be configured.
Create a notification rule for this subscriber using Notification Wizard in the SE-Viewer, see 'Creating Notification Rule' below.

Creating Notification Rule

Intercept Studio allows creating and modifying notification rules through the Notification Wizard. You may also use this wizard to create notification rules for newly added subscribers. After finishing the steps in the previous section, you should do following steps to configure SE-Viewer to use your new subscriber:

Open the Notification Wizard via the Tools menu of SE-Viewer.
Select 'Create new notification rule'.
Select your new subscriber type.
Set the notification rule name and appropriate settings.
Choose notification type (for example, for every event), and filtering for the rule.
Click Finish to update configuration.

Sample Code - FileSubscriber.cs

File synchronization not included in order to simplify the source code.

using System;

using System.IO;

using System.Xml;

using System.Reflection;

using AVIcode.Intercept.SEManager.Subscriber;

namespace AVIcode.Intercept.SEManager.Subscriber.FileLog

{

/// <summary>

/// SEManager file subscriber

/// </summary>

public class FileSubscriber : ISubscriber, ISubscriberConstruction

{

private string filePath;

private const string filePathKey = 'filePath';

public FileSubscriber()

{

}

/// <summary>

/// Initializes subscriber object (ISubscriberConstruction.Init)

/// </summary>

/// <param name='settings'></param>

public void Init(string settings)

{

XmlDocument settingsDocument = new XmlDocument();

settingsDocument.LoadXml(settings);

XmlNodeList paramNodes = settingsDocument.SelectNodes('/settings/param');

foreach(XmlNode param in paramNodes)

{

if(string.Compare(param.Attributes['key'].Value, filePathKey, true) == 0)

filePath = param.Attributes['value'].Value;

}

if(filePath != null)

{

if(!Path.IsPathRooted(filePath))

{

string directory = System.Reflection.Assembly.GetExecutingAssembly().Location;

string path = Path.GetDirectoryName(directory);

filePath = Path.Combine(path, filePath);

}

else

{

string message = string.Format('Parameter '{0}' was not found in the settings xml', filePathKey);

throw new SubscriberException(message);

}

/// <summary>

/// Log events to the subscriber (ISubscriber.LogEvent)

/// </summary>

/// <param name='url'></param>

/// <param name='eventID'></param>

/// <param name='newGroup'></param>

/// <param name='eventGroupID'></param>

/// <param name='eventClass'></param>

/// <param name='eventClassVersion'></param>

/// <param name='eventClassName'></param>

/// <param name='eventClassType'></param>

/// <param name='eventType'></param>

/// <param name='eventProperties'></param>

public void LogEvent(string url

,long eventID

, bool newGroup

, long eventGroupID

, string eventClass

, string eventClassVersion

, string eventClassName

, string eventClassType

, AVIcode.Intercept.SEManager.EventType eventType

, System.Collections.Hashtable eventProperties)

{

using(StreamWriter sw = File.AppendText(filePath))

{

string message;

if(eventProperties['isTestEvent'] != null && (bool)eventProperties ['isTestEvent'])

message = 'Test event notification';

else

message = string.Format('EventID: {0}

, Event type: {1}

, Description: {2}

, URL: {3}'

, eventID

, eventClassType

, eventProperties['description']

, url);

sw.WriteLine(message);

sw.Close();

}

Last update: Tuesday, June 08, 2010 02:08:25 PM