Working with EMS Alert Probe Monitor Configurations

Topaz EMS monitors are useful for capturing alerts and other event data from Enterprise Management Systems, automated support systems, and other management applications. By default, these monitors are configured to capture and transfer a variety of information to Topaz. As with other features in SiteScope, the Topaz EMS monitors can be customized as to the way that they handle events.

This section describes:

General EMS Configuration File Structure
Event Handler Structure
Special EMS Configuration File Entries
EMS Configuration File Examples
References
Logging EMS Events to a Topaz Database

General EMS Configuration File Structure

The EMS Configuration file allows you to customize the events that are being forwarded to Topaz. The file contains instructions on how to process the event as it arrives to SiteScope's EMS monitors. The configuration file is based on concept of event handlers - independent sections that contain instructions relevant to specific events. You can use this to customize the configuration to events that are originated in several different Enterprise Management Systems. This section describes the possible options within the configuration file and presents a number of examples.

Each Topaz EMS monitor type has a configuration file that containing one or more sets of event handlers. The individual configuration files for the EMS monitor types are stored in the location described as follows:

<SiteScope install path>/ems/<monitor_type>/main.config

where <SiteScope install path> is the SiteScope home path and <monitor_type> is the monitor type name (for example, Prism or Clarify).

The instructions that constitute the configuration file are grouped into event handlers. Each event handler contains a "matching condition", by which SiteScope can decide whether to use a particular event handler for an arriving event. When an event is being forwarded to Topaz, SiteScope iterates over the different event handlers in the configuration file, in the order they appear in the file, testing the "matching condition" of each handler. If a matching handler is found, SiteScope uses the instructions within that handler to process event and to forward it to Topaz.

Event Handler Structure

Each event handler has following structure:

[name]
Matching condition
Action directive
Tags

Instructions within the handler share the form name=expression, where name is a string, and expression is a valid boolean expression that is evaluated during the event forwarding.

The names of Matching condition, Action directive and additional directives start with dollar sign symbol ($). The names of tags should not start with dollar sign.

Comments are allowed in the configuration file. The comment starts with either #, ! or ; character and continues to the end of the line. The "block comments" are not supported.

Expression structure and available operations

The expression must be valid boolean expression. The expression can contain calls to the operators and functions defined below. The expression can access contents of the event that is being processed using the dollar sign ($) notation. For example, if the incoming event is SNMP Trap, then its enterprise OID can be accessed as $oid. Refer to the user guide of the relevant monitor type for names specific to monitor.

Matching Condition

The matching condition has the form:

$MATCH=Boolean expression

Where the boolean expression is one of the expressions listed in the table below

`Boolean expression(s)`	Description	Examples	True if..
<, <=, > , >=, ==, !=	Checks the numerical correctness of the expression. Can also be used with `UINT` or `DOUBLE` fields.	`$MATCH= $numberOfLines == 100`	`field $numberOfLines equals 100`
<, <=, > , >=, ==, !=		`$MATCH= $numberOfColumns <= 107`	`field $numberOfColumns equals 107 or less`
equals(String)	Checks for string equality.	`$MATCH= “ERROR”.equals($Status)`	`field $status equals the word ERROR`
equals(String)	Checks for string equality.	`$MATCH= $Status.equals(“ERROR”)`	`field $status equals the word ERROR`
true, false	Constant Boolean values.	`$MATCH= true`	`always true`
&&, \|\|	To be used in order to combine any of the above boolean expressions.	`$MATCH= $Status.equals(“ERROR”) \|\| $numberOfLines == 100`	`field $status equals the word ERROR or if field $numberOfLines equals 100`
time()	Returns the current type in seconds since January 1, 1970 format Can also be used with `DOUBLE` fields.	`$MATCH= $timeStampField > (time()-600)`	`the value of the $timefield is newer then ten minutes ago (` in seconds since January 1, 1970 format`)`
parseInt(String), parseDouble( String),	Use to convert strings to numeric values. Can also be used with `UINT` or `DOUBLE` fields.	`$MATCH= parseInt($Size) > 10`	`the string value in the $size field is an integer bigger then 10`
`str_to_seconds(String,String)`	Calculates the timestamp ( in seconds since `January 1, 1970` format) held in the first String using the format in the second string. Can also be used with `DOUBLE` fields.	`$MATCH=` str_to_seconds($time,”mm-dd-yyyy”) > time()	`the date specified in the $time field in the`”mm-dd-yyyy” format is after the current time
exist($field)	Checks for an existence of a field in the processed event	`$MATCH=exist($doesItExists)`	`Field $doesItExists exists in the incoming event`

Any of the above expressions can be used and the expression can refer to incoming event fields. The value of the expression, which can be either true or false, determines whether the event handler will be used to process the event or not.

Action directive

The action directive has form:

$ACTION=TOPAZ_BUS_POST | TOPAZ_POST | DISCARD]

The value of the Action directive defines whether the event will be processed and forwarded to Topaz, or discarded. This value will take effect only if the matching condition within the handler had been evaluated to positive value (i.e. to true). The table below describes the effect of the different actions.

`Action`	Description	To be used with…
`TOPAZ_BUS_POST`	Send the event to the Topaz bus. Do not send the event to the database	BAC and other online applications.
`TOPAZ_POST`	Sends the event to the Topaz bus and to the Topaz database	BAC and other online applications. ARCA and other offline applications.
`DISCARD`	Do not send the data to topaz	Events you wish to filter out.

Special EMS Configuration File Entries

In addition to the event handlers, the configuration file can contain special entries that affect the EMS integration engine as a whole. these values are grouped into the [$DEFAULT_PARAMETERS$] section. This section defines tags that are common for all handlers. Any tag can be set in this section; it will be used to create a reported value unless defined in the relevant event handler.

EMS Configuration File Examples

Example 1: Universal Event Handler:

[post them all]
$MATCH=true
$ACTION=TOPAZ_BUS_POST
u_iSeverityId:UINT=INFORMATIONAL
szAlarmText:STRING=”post them all handler received an event”

Note that the $MATCH directive in the handler is set to true. This causes every event to "match" the handler.

Example 2: Different event handlers for long and short events

[Handler for events with error status ]
$MATCH= $status.equals(“ERROR”)
$ACTION=TOPAZ_BUS_POST
u_iSeverityId:UINT=CRITICAL

[post them all]
$MATCH=true
$ACTION=TOPAZ_BUS_POST
u_iSessionId=10
u_iSeverityId:UINT=INFORMATIONAL

The "universal" handler is preceded with a handler which will match only events status field that equals the word “ERROR”. Every event that has this value in the $status field will be processed with first handler; other events will be processed with the second, the universal, handler.

References

String getStringProperty(String propertyName) return value of the event property or null if the property doesn’t exist in the event. Note that $name has the same effect.

Logging EMS Events to a Topaz Database

In order to send EMS events generated by the different sitescope monitors to the event database in Topaz:

Open the monitor’s main.config file.
Change the $ACTION directive to TOPAZ_POST in the relevant handlers. If you wish all event types to go to the database, change all $ACTION directives in the file to TOPAZ_POST.
locate the u_iSessionId parameter of type UINT and change its value to the id of existing EMS profile.