SiteScope User's Guide

Integration Monitor Configuration Files

Mercury Business Availability Center EMS Integration monitors are useful for capturing event and measurement 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 Mercury Business Availability Center. As with other features in SiteScope, the Mercury Business Availability Center Integration monitors can be customized as to the way that they handle data.

This section describes:

About the EMS Configuration File

All EMS monitors depend on configuration files which define the processing of incoming data and define the output sample forwarded to Business Availability Center. This section describes the configuration file syntax and structure.

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

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

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

where <SiteScope install path> is the SiteScope installation path, <monitor_type> is the monitor type name (for example, Tivoli , NetIQ , or HPOV ), and <name> is the name of an existing configuration file.

Note: When using the Database, Log File, and SNMP Trap Technology monitors, you must create an appropriate configuration file using one of the templates supplied before you configure the monitor.

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 or data arrives at the Integration monitor, it 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, the monitor uses the instructions within that handler to process event and perform the action defined for this handler (for example, forward it to Business Availability Center or discard). No further sections are checked after the first match. If no matches are found, the sample is discarded. By default, each file comes with an event handler that matches all events. An example of such a configuration file is shown below.

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

Event Handler Structure

Each event handler has following structure:

[name]
Matching condition
Action directive
Tags

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.

Matching Condition

The Match Condition must be a valid boolean expression. The expression can contain calls to the operators and functions defined below. The expression can access the 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 that monitor.

The matching condition has the form:

$MATCH=Boolean expression

where the Boolean expression is one of the expressions listed in the table below. When mentioned in the description, the expression can also be used to assign values into tags (see tag section below).

 

Boolean expression(s)

Description

Examples

True if

<, <=, > , >=, ==, !=

Checks the numerical correctness of the expression. Can be used with INT 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

$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 time in seconds since January 1, 1970 format. Can be used with DOUBLE fields.

$MATCH= $timeStampField > (time()-600)

the value of the $timeStampfield is newer then ten minutes ago ( in seconds since January 1, 1970 format )

parseInt(String),
parseDouble(String),

Use to convert strings to numeric values. The input string should be a valid representation of an Integer or a floating point number.
Note: calling this function on a string that cannot be interpreted as a number will cause an error and the incoming event will be dropped.
Can also be used with INT or DOUBLE fields.

$MATCH= parseInt($size) > 10

the string value in the $size field is an integer bigger then 10

str_to_seconds(Str1,Str2)

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,"yyyy-MM-dd HH:mm:ss.SSS") > time()

Note: use the following symbols to represent time data:

Year - `y'
Month - `M"
Day of month - `d'
Hour - `H'
Minute - `m'
Second - `s'

the date specified in the $time field in the " yyyy-MM-dd HH:mm:ss.SSS " format is later than the current time. You can search for SimpleDateFormat on the Inernet for more information

exist($field)

Checks for an existence of a field in the processed event

$MATCH= exist($status)

Field $status 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.

Basic String Expressions

The following table summarizes the string expressions that can be used in the configuration files:

Operation

Description

Examples

+

String concatenation

"trap type is " + $trap

Basic Conditional Expression

One conditional expression is supported; the ? operator. This operator can be used to compose 3 expressions into one: <Conditional part> ? <if true part> : <if false part>

Action Directive

The action directive has form:

$ACTION= TOPAZ_BUS_POST or TOPAZ_POST or DISCARD

The value of the Action directive defines whether the event will be processed and forwarded to Business Availability Center, 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

For use with

TOPAZ_BUS_POST(event)

Send the event to the Business Availability Center bus and Database.

Mercury Business Availability Center

TOPAZ_BUS_POST(ss_t)

Send the measurements to Application Management as SiteScope Data.

Mercury Business Availability Center

TOPAZ_POST

Sends the event to the bus and to the database

Note: For use with Topaz 4.5 and non-UDX data using the ems_type template

Auto Correlation

DISCARD

Do not send the data to Mercury Business Availability Center

Events you wish to filter out.

Note:

If you are using the measurement template, TOPAZ_BUS_POST(ss_t), the data is sent to the Application Management database as SiteScope data, and thus saved to the database. For details on the measurement template, see See Measurement Template (measurement.config).

Tags

In addition to directives, event handler contains tags. Each tag represents a field in the event that will be forwarded to Business Availability Center, whose value can be evaluated when the event arrives to the Integration monitor.

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 Business Availability Center. It can be either INT , DOUBLE or STRING . The default type is STRING .

By defining a tag, you can customize event forwarding to Business Availability Center and to get more value from the external applications that generate events that will be forwarded to the Business Availability Center Dashboard. If, for example, the monitor pulls out data from a database table column called AlertText , which contains a textual description of an alert, it is possible to send that data to Business Availability Center by adding the following line to an event handler section:

[event handler]
$MATCH=true
$ACTION=TOPAZ_BUS_POST(event)
text=$AlertText

Note:

When adding tags, always add them after the $MATCH and $ACTION .

Default EMS Configuration File Entry

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 default values for 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 overridden in the matched event handler. For each incoming event, this event handler will always be executed prior to the matched event handler.

EMS Configuration File Examples

Example 1: Universal Event Handler:

[post them all]
$MATCH=true
$ACTION=TOPAZ_BUS_POST(event)
Severity:INT=SEVERITY_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 and therefore every event is sent to the Business Availability Center Bus.

Example 2: Different event handlers for different severities.

[Error Handler]
$MATCH= $status.equals("ERROR")
$ACTION=TOPAZ_BUS_POST(event)
Severity:INT=SEVERITY_CRITICAL

[Info Handler]
$MATCH= $status.equals("INFO")
$ACTION=TOPAZ_BUS_POST(event)
Severity:INT=SEVERITY_INFORMATIONAL

[post them all]
$MATCH=true
$ACTION=TOPAZ_BUS_POST(event)
Severity:INT=SEVERITY_INFORMATIONAL

In the example above, an incoming event will be matched against the "Error Handler" event handler. If the handlers condition is true (that is, the value in the status field equals ERROR ), then an event with a field called Severity, whose value is SEVERITY_CRITICAL , will be sent to Mercury AM. An event can only be matched by a single handler: The first match will stop the processing and therefore once an event is matched by a section it will not be processed by the next handler.

If the event was not matched by the first handler, the second handler will come into action and its match (which looks for status of INFO ) will be used to decide whether the second handler needs to take action. Finally, If the event does not match the second handler, the third, universal handler will be evaluated.

Configuration File Templates

The EMS Technology monitors (EMS SNMP Trap, EMS Log File, and EMS Database) comes with a set of config file templates. The templates are available in the <Sitescope_install_path>\SiteScope\ems\templates\ folder. These templates include:

Event Template (event.config)

This template is used for extracting events collected by external system and importing them to Business Availability Center. For further details on this sample template see the section on Configuring the Event Template below.

Measurement Template (measurement.config)

This template is used for extracting measurements collected by external system and importing them to Business Availability Center. The measurements will be reported to Business Availability Center as SiteScope measurements. The measurement template defines a mandatory structure. For further details on this sample template see the section on Configuring the Measurement Template below.

Note:

Use only the mandatory and optional fields defined in the templates when working with the default configuration file templates. See the tables in the following sections for more information.

EMS Type Template (main.config)

This type is provided for backwards compatibility with Topaz 4.5 FP2 or earlier and for Auto Correlation. For further details on this sample template see the section on Configuring the EMS Type Template below.

The sections below describe considerations for each of the templates.

Note:

You should make a backup copy of the template configuration files and use a copy of the template files for any modifications that your make. This will allow you to restore the default configuration if necessary.

Note:

The templates must be edited prior to use. All mandatory fields must be set in the template so that the applicable monitor will be configured correctly.

Configuring the Event Template

The tables below list mandatory and optional values for the Event Template. An example configuration is shown below the table.

Note:

The Event Template is used for the Integration monitor types with Mercury Application Management/Business Availability Center 5.0 and later.

Mandatory Values for the Event Template

 

Field Name

Type

Description

Example

time_stamp

DOUBLE

Time stamp in the seconds since Jan 1st 1970 format

time_stamp:DOUBLE=str_to_seconds($time,"yyyy-MM-dd HH:mm:ss.SSS").

severity

INT

One of the following severities:
SEVERITY_UNKNOWN SEVERITY_INFORMATIONAL SEVERITY_WARNING SEVERITY_MINOR SEVERITY_MAJOR SEVERITY_CRITICAL

severity:INT=SEVERITY_MINOR

severity_name

STRING

One of the following strings:
"Unknown"
"Informational"
"Warning"
"Minor"
"Major"
"Critical"

severity_name="Minor"

target_name

STRING

Name of device or host that generated the event

target_name=$hostName

status

STRING

Status of event in external EMS terminology

status="OPEN"

subject

STRING

Subject of event (e.g. CPU , SAP application, Hard Disk ).
middle / high level of hierarchy describing the event source The hierarchy describing an event is in the following format:

monitor_group (optional) --> object (optional) --> subject --> instance

more levels can be added above monitor monitor_group by using logical_group, and attr1 - 5

subject="DISK"

instance

STRING

Instance of subject that generated the event (e.g D:\ ). lowest level of hierarchy describing the event source

instance="E:\\"

description

STRING

Textual description of event

description="free space on drive e is below 10%"

data_source

STRING

System that generated the event

data_source="HP OVO"

Optional Values for the Event Template

The tables below list optional values for the Event Template. An example configuration is shown below the table.

 

Field Name

Type

Description

Example

target_ip

STRING

IP of host or device that generated the event

target_ip=$IPString

object

STRING

Optional level in the hierarchy describing the event source

object="OS"

event_id

STRING

Unique identifier of this event

event_id=$id

logical_group

STRING

Logical grouping of this event

logical_group="error messages"

monitor_group

STRING

Monitor group that reported this event

monitor_group="log monitors on \\hostname"

orig_severity_name

STRING

Severity in external EMS terminology

orig_severity_name ="Cleared"

acknowledged_by

STRING

Name of user that acknowledged this event

acknowledged_by =$username

owner

STRING

Name of user who owns this event

owner="admin"

value

DOUBLE

Use to transfer numerical values from the event

value=$thresholdViolated

attr1

STRING

Extra data slots

attr1=$history

attr2

STRING

Extra data slots

attr2=$moreHistory

attr3

STRING

Extra data slots

attr3="Design"

attr4

STRING

Extra data slots

attr4=$MonitorOutput

attr5

STRING

Extra data slot for long strings

attr5=$Longhistory

Conditional Expression Example 1:

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 .

Conditional Expression Example 2:

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 the value 50 . Otherwise, if the sixth variable binding holds string green , then u_iSeverity tag will have the value 10 . Otherwise, if the variable binding holds string yellow , the tag will have the value 30 , and if none of the above conditions is true, then the tag will have the value 20 .

Example Event File

In the example below , two types of events are sent: the first are events of status "OPEN" and the second are events cleared by a user. The data is retrieved from incoming event fields using the $ notation. All other events are discarded by the last handler.


[$DEFAULT_PARAMETERS$]
################################################
# NOTE: the following parameters are mandatory #
################################################
time_stamp:DOUBLE=str_to_seconds($time,"yyyy-MM-dd HH:mm:ss.SSS")
severity:INT= SEVERITY_UNKNOWN
severity_name="Unknown"
target_name=$Device
status=$Status
subject="EMS X Events"
instance=$target
description=$description
data_source="EMS X"

#send an open event with the value in value fields and with the event id
[OPEN events]
$MATCH="OPEN".equals($Status)
$ACTION=TOPAZ_BUS_POST(event)
value:DOUBLE=parseDouble($threshold)
event_id=$uid

#send clear events with the event id and acknowledging username
[clear events]
$MATCH="CLEAR".equals($Status)
$ACTION=TOPAZ_BUS_POST(event)
event_id=$uid
acknowledged_by=$ClearedBy

[event sink]
$MATCH=true
$ACTION=DISCARD

Configuring the Measurement Template

The table below lists mandatory values for the Measurement Template. An example template is shown below the table.

Note:

The Measurement Template is used for the Integration monitor types with Mercury Application Management/Business Availability Center 5.0 and later.

 

Field Name

Type

Description

Example

TimeStamp

DOUBLE

time stamp in the seconds since Jan 1st 1970 format

TimeStamp:DOUBLE=time()

Quality

INT

quality in SiteScope terms. Possible values are: QUALITY_ERROR, QUALITY_WARNING, QUALITY_GOOD

Quality:INT= QUALITY_ERROR

MonitorName

STRING

logical monitor name.

MonitorName="NT cpu Monitor"

MonitorState

STRING

The monitor status, for example, N\A, Good, Error, and so forth.

MonitorState="Received " + $count + " events"

MonitorType

STRING

The monitor type

MonitorType="System Monitor"

TargetName

STRING

The target of this monitor (e.g. host name )

TargetName=$Device

MeasurementName(N)

STRING

Name Nth measurement

MeasurementName(1)="CPU Temperature"

Value(N)

DOUBLE

Value of Nth measurement

Value(1):DOUBLE=$CPUTemperature

Example Measurement Template

In the example below , two measurements are sent: the first one takes its name from the $legend field and takes the value from the $value field. A second measurement uses the constant name CPU Temperature which receives its value from the $CPUTemp field.

 

#########################################
# Site scope measurement config file #
# use this file to send measurements to Application Management #
#########################################
[$DEFAULT_PARAMETERS$]
# time stamp in the seconds since Jan 1st 1970 format.
TimeStamp:DOUBLE=str_to_seconds($time,"yyyy-MM-dd HH:mm:ss.SSS")
# quailty in SiteScope terms QUALITY_ERROR, QUALITY_WARNING, QUALITY_GOOD
Quality:INT=QUALITY_ERROR
# logical monitor name
MonitorName=$kpName
MonitorType="NetIQ measurements"
MonitorState="The monitor status is: "+ $status
#target, e.g. host name
TargetName=$parentMachineName
#measurement name
MeasurementName(1)=$legend
#value as double
Value(1):DOUBLE=parseDouble($value)
#measurement name
MeasurementName(2)="CPU Temperature"
#value as double
Value(2):DOUBLE=parseDouble($CPUTemp)
####################################################
# In order to send more than one measurement per DB row #
# add pairs #
# MeasurementName(*)= #
# Value(*):DOUBLE= #
# where * = 1,2,.,n #
# ##################################################

[allR]
$MATCH=true
$ACTION=TOPAZ_BUS_POST(ss_t)

When specifying more then one measurements in the template, a separate sample will be sent with each of the measurements.

Note:

when specifying multiple measurements per file, the measurement numbering must be consecutive.

In the case of failure, errors will appear in the error.log but the error will not affect the monitor state.

Configuring the EMS Type Template

Note:

The EMS Type Template is used for backwards compatibility of the Integration monitor types with Topaz 4.5 FP2 or earlier and for Auto Correlation.

This section describes the mandatory fields for defining this template .

The Business Availability Center Alert Log report, TBA and the Business Availability Center Auto Correlation application expect certain fields to appear within the reported event. The EMS integration engine provides sensible defaults for these fields; however you can get more value by creating fields to provide exact value for these fields.

Mandatory Fields for the EMS Type Template

The following table summarizes the mandatory fields for the EMS Type Template:

 

Field name

Field type

Field description

Valid value range

Field default value

szSeverityName

STRING

Name of the event severity

String representation of the event severity

Name of u_iSeverityId field value, if specified, otherwise the word "UNKNOWN"

szEMSAlarmTypeName

STRING

Name correspond to type ID

NO DEFAULT

Tags for Alert Log and Auto Correlation

Tags expected by the Business Availability Center Alert Log and the Business Availability Center Auto Correlation applications:

 

Field name

Field type

Field description

Valid value range

Field default value

u_iSeverityId

INT

Business Availability Center severity id of the event.

One of :
UNKNOWN(0),
INFORMATIONAL(10),
WARNING(20),
MINOR(30),
MAJOR(40),
CRITICAL(50)

Note: Either numerical or mnemonic value can be used, that is, u_iSeverityId=10 , or u_iSeverityId=MAJOR

UNKNOWN severity id.

szAlarmText

STRING

The event short text

Any text up to 256 characters

"GenericProbe Alert" string

szAlarmDesc

STRING

Long text of the event

Any text up to 2000 characters

String contains all fields from the event in form [name1=value1;...]

dAlarmTimeStamp

DOUBLE

Time of the event

The difference, measured in seconds, between the current time and midnight, January 1, 1970 UTC.

Current UTC time in seconds

u_iSessionId

INT

EMS Profile id the event to be stored in

Valid EMS Profile ID

SiteScope's Profile ID

szTargetHostIP

STRING

IP of the host the event occurred on

A string that contains 4 decimal numbers, separated by dots ("%d.%d.%d.%d")

Host IP of szTargetHostName field value, if specified, otherwise, local machine IP

szTargetHostName

STRING

Host name of the machine the event occurred on

Host name

local machine name

u_iEMSAlarmTypeId

INT

ID of the alarm type

NO DEFAULT

Reserved Tags in the EMS Type Template

Following tags are used internally by the EMS integration engine.

Note:

Re-defining these tags can lead to incorrect event forwarding.

 

Field name

Field type

u_iTargetTypeId

INT

u_iTargetSubTypeId

INT

u_iAlarmId

INT

u_iNmmtHostId

INT

u_iEMSId

INT

Logging Events to Business Availability Center for Auto Correlation

In order to use EMS events in Auto-Correaltion (or for backward compatibility to Root-Cause Analysis), you must modify the configuration file for the applicable Integration monitor using the following steps.

To configure monitors to send data to the event database for use by Auto Correlation:

  1. On the SiteScope server where the applicable monitor instance is configured, Open the applicable monitor's main.config file using a text editor.
  2. Save the file to a new filename (for example, mymain.config) in the same directory.
  3. In the new file, change the $ACTION directive to TOPAZ_POST for the relevant handlers. If you wish all event types to go to the database, change all $ACTION directives in the file to TOPAZ_POST.
  4. Locate the u_iSessionId parameter of type UINT and change its value to the id of the existing EMS profile (created in the Business Availability Center Console).
  5. Save the changes to the configuration file
  6. Edit the applicable monitor instance and change the EMS Configuration File Path setting to point to the new configuration file (in this example, mymain.config).

Mercury
Copyright © 2004 Mercury Interactive Corporation.
All rights reserved.

Documentation comments or suggestions?
Please send feedback to documentation@mercury.com