SiteScope User's Guide

EMS SNMP Trap Monitor Configuration File Reference

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 monitor. The configuration file is based on concept of event handlers - independent sections that contain instructions relevant to specific events. This allows customizing the configuration to events that are originated in several different Enterprise Management Systems.

The default configuration file that is provided with installation contains single section with instructions to passing every incoming trap to Topaz Bus (for later use by Topaz Business Availability). By editing the file you can modify the default behavior.

Note: Always have a copy of the default configuration file available, so that you will be able to consult the original settings if necessary.

How the Configuration File is Used

Every time a trap enters the system, the MATCH directive from each section is evaluated, in the order the sections appear in the configuration file. Once a section “matches”, the instructions in it are used to process a trap; no further sections are checked. If no “matching” section is found, the trap is discarded.

Note: The directives and sections are cached in the memory, so there is no performance penalty.

General configuration structure

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 event is being forwarded to Topaz, SiteScope iterates over event handlers in the configuration file, in order they appear in the file, testing the "matching condition" of each handler. If a matching handler is found, SiteScope uses instructions within that handler to process event and to forward it to Topaz. If no matching event handler is found, default configuration is used, see details below.

Event Handler Structure

Each event handler has following structure:

[name]
Matching condition
Action directive
Additional directives
Tags

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

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

Matching Condition

The matching condition has form

$MATCH=Boolean expression

The Boolean expression can is a valid one-line Java expression that can refer to event contents. According to the expression and to values of the contents that the expression refers to, its value can be either true, or false. This value, eventually, determines whether the event handler matches the event or not.

Action directive

The action directive has form

$ACTION=[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). If the action directive has value TOPAZ_POST, the event will be processed and forwarded to Topaz. If the action directive has value DISCARD, the event will be discarded, i.e. not passed to Topaz.

Additional directives

Right now there is only one additional directive:

$COPY_ALL_FIELDS=

The value of the directive is not used. If the directive is present, all contents of the event will be passed to Topaz if the matching condition yields positive result and the action is set to TOPAZ_POST.

Tags

In addition to directives, event handler contains tags. Each tag represents a field in the event that will be forwarded to Topaz, which's value can be evaluated when the event arrives to SiteScope.

General form of a tag is:

name[:type]=value

The name is any string without spaces or dollar signs ($). The type specifies the type of field as reported to Topaz - it can be either UINT, DOUBLE or STRING. Default type is STRING.

By defining a tag, one can customize event forwarding to Topaz and to get more value from the external applications that generate events that will be forwarded to Topaz Business Availability.

Expected Tags

The Topaz Alert Log application and the Topaz Root Cause Analysis application expect certain fields to appear within the reported event. The SiteScope EMS integration engine provides sensible defaults for these fields; however you can get more value by creating tags to provide exact value for these fields.

Following tables summarizes the expected tags:

Tags expected by the Topaz Business Availability Application:

Tags expected by the Topaz Alert Log and the Topaz Root-Cause Analysis applications:

Reserved Tags

Following tags are used internally by the EMS integration engine. Redefining these tags can lead to incorrect event forwarding.

Special Configuration Entries

In addition to the event handlers, the configuration file can contain special entries that affect the EMS integration engine as a whole. Currently, these sections are grouped into two special sections: the [$CONFIG$] section and the [$DEFAULT_PARAMETERS$] section:

[$CONFIG$] section

This section contains directives that affect the EMS integration engine as a whole. It must be the first section in the configuration file. Following entries are available for this section:

Run Policy:

There’s a essential possibility of run-time exception, since there’s a possibility to write an expression that has valid syntax, but would not evaluates into correct value ( for example, 2/0 ). The file allows controlling engine behavior by defining following special section:

RunPolicy=[NEXT_ON_EXCEPTION|DISCARD_ON_EXCEPTION]

If the RunPolicy entry is set to NEXT_ON_EXCEPTION, then the EMS integration engine will continue looking for matching event handler. If the RunPolicy is set to DISCARD_ON_EXCEPTION, then the event will be discarded;

[$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.

Examples

Example 1: Universal Event Handler:

[post them all]
$MATCH=true
$ACTION=TOPAZ_POST
$COPY_ALL_FIELDS=
u_iSeverityId:UINT=INFORMATIONAL
szAlarmText:STRING=”post them all handler received an event”
szAlarmDesc=print_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 more than Ten fields]

$MATCH= size () > 10
$ACTION=TOPAZ_POST
$COPY_ALL_FIELDS=
u_iSessionId=10
u_iSeverityId:UINT=INFORMATIONAL
szAlarmDesc=print_event()
szAlarmText:STRING=”received event has ” + size() + “ fields.”

[post them all]
$MATCH=true
$ACTION=TOPAZ_POST
$COPY_ALL_FIELDS=
u_iSessionId=10
u_iSeverityId:UINT=INFORMATIONAL
szAlarmDesc=print_event()

The "universal" handler is preceded with a handler which will match only events with more than 10 fields. Every event that has more than ten fields will be processed with first handler; others will be processed with the second, the universal, handler.

Example 3: Different event handlers for long and short events, with common parameters within special section

# Common parameters for all sections
[$DEFAULT_PARAMETERS$]
u_iSessionId=10
$COPY_ALL_FIELDS=
u_iSeverityId:UINT=INFORMATIONAL
szAlarmDesc=print_event()

[Handler for events with more than ten fields]
$MATCH= size () > 10
$ACTION=TOPAZ_POST
szAlarmText:STRING=”received event has ” + size() + “ fields.”

[post them all]
$MATCH=true
$ACTION=TOPAZ_POST

Expression structure and available operations

The expression must be valid one line Java expression. The expression can contain calls to Java string processing functions, Java conditional expressions and operators. For example, following expression can be used in the configuration file:

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 user guide of the relevant Monitor for names specific to monitor.

If the expression contains function call without any parameters, the invocation braces (()) are optional. For example, the expressions  

“Some string constant”.length and “Some string constant”.length() are equivalent

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.

Accessing contents of SNMP Trap

All kinds of expressions can access the contents of the incoming SNMP trap.

In general,  the trap’s contents are similar to names that appear in the <sitescope_install gt;/SiteScope/logs/snmptrap.log file.

Following table summarizes the references to the contents of the trap:

Basic String Expressions

The following table summarizes the string expressions that can be used in the EMS SNMP Trap Monitor configuration files:

Basic Boolean Expressions

The following table summarizes the string expressions that can be used in the EMS SNMP Trap Monitor configuration files:

Example:

$MATCH=$var3.equals(“prism”)

In this example, the value of the third variable binding in the trap (“$var3”) is compared with string “prism”. If the third variable binding contains the word “prism”, then the boolean expression will be evaluated to “true”, and the section that contain the $MATCH directive will be “matched”. Otherwise, the boolean expression will be evaluated to “false”, and the section not be “matched”.

Basic Conditional Expression

Actually, there is only one conditional expression, the “?:” operator. This operator composes 3 expressions into one:            <Conditional part> ? <if true part> : <if false part>

Example:

u_iSeverityId:UINT=$var6.equals(“red”) ? 50 : 10

In this example, the value of sixth variable binding is compared to string “red”. If the variable binding indeed is equal to string “red”, then the value of the u_iSeverity tag will be set to 50, otherwise it will be set to 10.

Another example:

u_iSeverityId:UINT=$var6.equals(“red”) ? 50 : $var6.equals(“green”) ? 10 : $var6.equals(“yellow”) ? 30 : 20

In this example, we are chaining the conditional operator into a decision chain. If the sixth variable binding holds string “red”, then u_iSeverity tag will have value 50. Otherwise, if the sixth variable binding holds string “green”, then u_iSeverity tag will have value 10. Otherwise, if the variable binding holds string “yellow”, the tag will have value 30, and if no above conditions is true, then the tag will have value 20.

Copyright © 2004 Mercury Interactive Corporation.
All rights reserved.

Documentation comments or suggestions?
Please send feedback to documentation@merc-int.com