Skip to main content

USER_DEFINED Section

User-defined monitors are specified via one or more <user_defined> sections, per the following template:


<user_defined>

<alarm_group>____</alarm_group>

<alarm_level>____</alarm_level>

<log_name>___</log_name>

<window>____</window>

<start_image>____</start_image>

<log>NONE | SCANS | EVENTS</log>

<outputs>_x_ _y_ ...</outputs>

<alarm>>

<event>____</event>

<action>____</action>

<sleep>____</sleep>

</alarm>

<normal>

<event>____</event>

<action>____</action>

<sleep>____</sleep>

</normal>

</user_defined>

All entities within <user_defined> are optional except <log_name> and <start_image>. Duplicate entities constitute an error.

<alarm_group> and <alarm_level> are discussed in the "Multiple Alarm Levels" section. Either both must be specified or neither may be specified.

<log_name> is the identifier to be associated with this user-defined monitor, is limited to 64 characters (alpha, numeric, '-' and '_'), and should be unique across multiple <user_defined> sections.

<start_image> is the complete pathname of a Shell script or program, along with any required start parameters, to be executed to produce values to be logged and to determine if an alarm condition exists. The time stamp for the current scan cycle will be appended to <start_image> to execute the monitor. Its format is as returned by the standard UNIX 'date' command, e.g., "Tue Aug 14 11:50:07 CDT 2016". <window> defines when the specification is to be active. An example follows in a couple paragraphs.

<outputs> define the values to be generated by <start_image>. "_x" and "_y" are used in the template as place-holders, the user is free to choose any name desired. As many as required can be defined. Value names are limited to 64 characters (alpha, numeric, '-' and '_') and need not be unique across multiple <user_defined> sections.

<start_image> will be executed synchronously, i.e., SMA_RM will wait for it to complete. It must produce, to standard output (stdout), an indicator of status and a listing of its return values as specified in <outputs>. The first line of output must be either ALARM or NORMAL. Each additional line of output, one for each generated value, is of the form "VALUE_NAME=value" (no quotes). "VALUE_NAME" is one of the names in the associated <outputs> spec, and must appear in the order listed within the <outputs>. Spaces may be used around the '='. "value" constitutes everything from the first non-space/tab after the '=' to end-of-line (including trailing spaces/tabs). To include leading spaces/tabs in "value", change the '=' to '=\' (no embedded spaces), in which case "value" extends from the character immediately following the '\' to end-of-line.

Upon completion of <start_image>, SMA_RM will inspect the returned standard output and log returned values as directed by the <log> spec. If, from one scan to the next, the first line of output changes from NORMAL to ALARM (or is initially ALARM), <alarm> defines what is to occur (as discussed in the next section). If the first line changes from ALARM to NORMAL, then <normal> is executed. Along with %LOG_NAME%, which is the contents of <log_name>, the returned values for the defined output variables will be available as event variables for use within <alarm> and <normal>.

For an example of a user-defined monitor, consider the following spec:


<user_defined>

<log_name>checker</log_name>

<start_image>/usr/me/check this that "the other"</start_image>

<log>SCANS</log>

<outputs>hokus pokus rokus disk</outputs>

<alarm>

<event>$%log_name% -- hokus=%HOKUS%, pokus=%POKUS%</event>

</alarm>

</user_defined>

When the timestamp for the current scan is included, the monitor would be executed with a command line similar to:

/usr/me/check this that "the other" "Tue Aug 14 11:50:07 CDT 2016"

If 'check' is a UNIX Shell script, it would see five command-line arguments:


$0 = /usr/me/check

$1 = this

$2 = that

$3 = the other

$4 = Tue Aug 14 11:50:07 CDT 2016

And it might return, via standard output, something like:


ALARM

HOKUS = 25

POKUS =\ not so fast!!!

ROKUS = does not include preceding spaces!!!

DISK=Just tossing a monkey wrench into the system...

%HOKUS%, %POKUS%, %ROKUS% and %DISK% would get each logged, without regard to the alarm/normal status, since <log> is set to SCANS. Then, assuming that two spaces appear after "25", and that this is the initial execution (the first line of output is ALARM), the event specified in <alarm> would get sent to SAM, i.e.:

$checker -- hokus=25 , pokus= not so fast!!!

Notice that since no <normal> is defined, nothing will occur when the first line of output changes to NORMAL.

The following is an example of a script for a user-defined monitor to report the number of files in the specified directory and to base the reported normal/alarm status on that number being less than a specified value:


#!/bin/sh

if [ $2 -eq 80 ]

then

rm -f lll 2>&-

ls -l $1|wc -l >lll

fi

n=`cat lll`

if [ $n -ge $2 ]

then

echo ALARM

else

echo NORMAL

fi

echo directory=$1

echo number_of_files=$n

Start parameter $1 is the directory to be sized, and $2 is the alarm boundary. The significance of the '80' in line 2 is that 80 is the first level alarm (refer to Multiple Alarm Levels). If used in a multi-level alarm set-up, higher-level alarms must alarm at values greater than 80, i.e., the first reference to this script in a <user_defined> must have '80' as the second start parameter within entity <start_image>. The output variables would be defined with an "<outputs>directory number_of_files</outputs>" entity within the <user_defined>.