9 Configuring Notifications

9.2.2.1 Adding a Notification Method based on an OS Command

You can specify an Operating System command or script that will be called in Notification Rules. The OS Command is run as the user who started the Management Service. The OS command (or script) must exist and be placed on each Management Service host machine that connects to the Management Repository.

The following information is required for each OS command notification method:

• Name

• Description

  Both Name and Description should be clear and intuitive so that the function of the method is clear to other administrators.

• OS Command

You must enter the full path of the OS command or script in the OS command field (for example, /u1/bin/myscript.sh). For environments with multiple Management Services, the path must be exactly the same on each machine that has a Management Service. Command line parameters can be included after the full path (for example, /u1/bin/myscript.sh arg1 arg2).

To define a notification method based on an OS command, perform the following steps.

1. Create an OS command on the repository host machine.

   Create an OS Command on each Management Service machine that connects to the Management Repository. The OS Command should be an absolute path name and must be the same on each Management Service host machine, for example, /u1/bin/logSeverity.sh. The command is run by the user who started the Management Service. If an error is encountered during the running of the OS Command, the Notification System can be instructed to retry the sending of the notification to the OS Command by returning an exit code of 100. The procedure is initially retried after one minute, then two minutes, then three minutes and so on, until the notification is a day old, at which point it will be purged.

   Example 9-3 shows the parameter in emoms.properties that controls how long the OS Command can execute without being killed by the Management Service. This is to prevent OS Commands from running for an inordinate length of time and blocking the delivery of other notifications. By default the command is allowed to run for 30 seconds before it is killed.

   Example 9-3 Parameter in emoms.properties File

   # The amount of time in seconds after which an OS Command started by the
   # Notification System will be killed if it has not exited
   # em.notification.os_cmd_timeout=30
   
   

2. Add this OS command as a notification method that can be called in Notification Rules. See "Adding a Notification Method based on an OS Command" .

3. Define a notification rule (choose the targets and conditions for which you want to be notified), and associate the OS command with the rule. See "Creating Your Own Notification Rules".

Example 9-4 shows an example of the required information.

Name Trouble Ticketing
Description Notification method to log trouble ticket for a severity occurrence
OS Command /private/mozart/bin/logTicket.sh

Information about the metrics in alert can be made available to your OS notification method. See "Passing Metric Severity Information" for more details.

9.2.2.2 Adding a Notification Method Based on a PL/SQL Procedure

Before setting up the method, the procedure must be created on the repository database. Using the database account of the repository owner (such as SYSMAN).

The procedure must have the following signature:

PROCEDURE p(severity IN MGMT_NOTIFY_SEVERITY)

Information about the metrics in alert can be made available to your PL/SQL procedure. See "Passing Metric Severity Information" for more details.

Next, create a notification method based on your PL/SQL procedure. The following information is required when defining the method:

• Name

• Description

• PLSQL Procedure

You must enter a fully qualified procedure name (for example, OWNER.PKGNAME.PROCNAME) and ensure that the owner of the Management Repository has execute privilege on the procedure.

To define a notification method based on a PL/SQL procedure, perform the following steps.

1. Create the PL/SQL procedure on the repository database using the following procedure specification:

   PROCEDURE p(severity IN MGMT_NOTIFY_SEVERITY)

   If an error is encountered during the running of the procedure, the Notification System can be instructed to retry the sending of the notification to the procedure by raising a user defined exception that uses the error code -20000. See the example above. The procedure initially retried after one minute, then two minutes, then three minutes and so on, until the notification is a day old, at which point it will be purged.

2. Add this PLSQL procedure as a notification method that can be called in Notification Rules. See "Adding a Notification Method Based on a PL/SQL Procedure".

   Make sure to use a fully qualified name that includes the schema owner, package name and procedure name. The procedure will be executed by the repository owner and so the repository owner must have execute permission on the procedure.

3. Associate the PL/SQL procedure with a notification rule.

An example of the required information is shown in Example 9-5.

Name Cleanup error log
Description Notification method to clean up the error log table
PLSQL Procedure mgmt_rep.log_util.cleanup_log

There can be more than one PL/SQL-based method configured per system.

For information about the severity types that relate to a target's availability, and how metric severity information is passed to the PLSQL procedure, see "Passing Metric Severity Information" for more details.

9.2.2.3 Adding a Notification Method Based on an SNMP Trap

Enterprise Manager supports integration with third-party management tools through the SNMP. For example, you can use SNMP to notify a third-party application that a selected metric has exceeded its threshold.

The trap is an SNMP Version 1 trap and is described by the MIB definition shown at the end of this chapter. See "Management Information Base (MIB)".

For more comprehensive configuration information, see the documentation specific to your platform; SNMP configuration differs from platform to platform.

You must provide the name of the host (machine) on which the SNMP master agent is running and other details as shown in the following example. In Example 9-6, the SNMP host will receive your SNMP traps.

Name HP OpenView Console
Description Notification method to send trap to HP OpenView console
SNMP Trap Host Name machine1.us.oracle.com
SNMP Host Port 162
SNMP Community public
This SNMP host will receive your SNMP traps.

Metric severity information will be passed as a one-line message in the SNMP trap.

An example SNMP Trap is shown in Example 9-7. All information is in one line which is sent as a variable embedded in the SNMP Trap.

Tue Oct 28 05:00:02 2003

Command: 4
   Enterprise: 1.3.6.1.4.1.111.15.2
   Agent: 138.1.6.200
   Generic Trap: 6
   Specific Trap: 1
   Time Stamp: 8464:39.99
   Count: 11

Name: 1.3.6.1.4.1.111.15.1.1.1.2.1
   Kind: OctetString
   Value: "mydatabase"

Name: 1.3.6.1.4.1.111.15.1.1.1.3.1
   Kind: OctetString
   Value: "Database"

Name: 1.3.6.1.4.1.111.15.1.1.1.4.1
  Kind: OctetString
  Value: "myhost.com"

Name: 1.3.6.1.4.1.111.15.1.1.1.5.1
   Kind: OctetString
   Value: "Owner's Invalid Object Count"

Name: 1.3.6.1.4.1.111.15.1.1.1.6.1
   Kind: OctetString
   Value: "Invalid Object Owner"

Name: 1.3.6.1.4.1.111.15.1.1.1.7.1
   Kind: OctetString
   Value: "SYS"

Name: 1.3.6.1.4.1.111.15.1.1.1.8.1
   Kind: OctetString
   Value: "28-OCT-2003 04:59:10 (US/Eastern GMT)"

Name: 1.3.6.1.4.1.111.15.1.1.1.9.1
   Kind: OctetString
   Value: "Warning"

Name: 1.3.6.1.4.1.111.15.1.1.1.10.1
   Kind: OctetString
   Value: "12 object(s) are invalid in the SYS schema."

Name: 1.3.6.1.4.1.111.15.1.1.1.11.1
   Kind: OctetString
   Value: "Database Metrics"

Name: 1.3.6.1.4.1.111.15.1.1.1.12.1
   Kind: OctetString
   Value: "SYSMAN"

9.2.3.1 Passing Information to an OS Script or Executable

The notification system passes severity information to an OS script or executable using system environment variables. Conventions used to access environmental variables vary depending on the operating system:

• UNIX: $ENV_VARIABLE

• Windows:%ENV_VARIABLE%

The notification system sets the following environment variables before calling the script. The script can then use any or all of these variables within the logic of the script.

Your script may reference some or all of these variables.

Example 9-8 shows an OS command script appending environment variable entries to a log file.

Example 9-8 logs a severity occurrence to a file server. If the file server is unreachable then an exit code of 100 is returned to force the Oracle Management Service Notification System to retry the notification

#!/bin/ksh

LOG_FILE=/net/myhost/logs/severity.log
if test -f $LOG_FILE
then
echo $TARGET_NAME $MESSAGE $TIMESTAMP >> $LOG_FILE
else
   exit 100
fi

Example 9-9 shows an OS script that logs alert information to the file 'alertmsg.txt'. The file is saved to the /u1/results directory.

#!/usr/bin/sh
echo "Alert logged:" > /u1/results/alertmsg.txt
echo "\n" >> /u1/results/alertmsg.txt
echo "target name is " $TARGET_NAME >> /u1/results/alertmsg.txt
echo "target type is " $TARGET_TYPE >> /u1/results/alertmsg.txt
echo "target is on host " $HOST >> /u1/results/alertmsg.txt
echo "metric in alert is " $METRIC >> /u1/results/alertmsg.txt
echo "metric index is " $KEY_VALUE >> /u1/results/alertmsg.txt
echo "timestamp is " $TIMESTAMP >> /u1/results/alertmsg.txt
echo "severity is " $SEVERITY >> /u1/results/alertmsg.txt
echo "message is " $MESSAGE >> /u1/results/alertmsg.txt
echo "notification rule is " $RULE_NAME >> /u1/results/alertmsg.txt
echo "rule owner is " $RULE_OWNER >> /u1/results/alertmsg.txt
exit 0

Example 9-10 shows a script that sends an alert to an HP OpenView console from Enterprise Manager Grid Control. When a metric alert is triggered, the Enterprise Manager Grid Control displays the alert. The HP OpenView script is then called, invoking opcmsg and forwarding the information to the HP OpenView management server.

/opt/OV/bin/OpC/opcmsg severity="$SEVERITY" app=OEM msg_grp=Oracle msg_text="$MESSAGE" object="$TARGET"

9.2.3.2 Passing Information to a PL/SQL Procedure

The notification system passes severity information to a PL/SQL procedure using the MGMT_NOTIFY_SEVERITY object. An instance of this object is created for every alert. When an alert occurs, the notification system calls the PL/SQL procedure associated with the notification rule and passes the populated object to the procedure. The procedure is then able to access the fields of the MGMT_NOTIFY_SEVERITY object that has been passed to it.

Table 9-2 lists all metric severity attributes that can be passed:

When a severity occurs for the target, the notification system creates an instance of the MGMT_NOTIFY_SEVERITY object and populates it with values from the severity. The severity codes in Table 9-3 have been defined as constants in the MGMT_GLOBAL package and can be used to determine the type of severity in the severity_code field of the MGMT_NOTIFY_SEVERITY object. See Example 9-11.

CREATE TABLE alert_log (target_name VARCHAR2(64),
                                                alert_msg VARCHAR2(4000),
                                                occured DATE);

PROCEDURE LOG_CRITICAL_ALERTS(severity IN MGMT_NOTIFY_SEVERITY)
IS
BEGIN
        -- Log all critical severities
   IF severity.severity_code = MGMT_GLOBAL.G_SEVERITY_CRITICAL
   THEN
        BEGIN
                INSERT INTO alert_log (target_name, alert_msg, occured)
                VALUES (severity.target_name, severity.message,
                                severity.collection_timestamp);
        EXCEPTION
        WHEN OTHERS
        THEN
        -- If there are any problems then get the notification retried
                RAISE_APPLICATION_ERROR(-20000, 'Please retry');
                END;
                COMMIT;
   END IF;
END LOG_CRITICAL_ALERTS;

9.10.2.1 Variable Name

Syntax

Maps to the SYNTAX element of SNMP MIB definition, Version 2.

Max-Access

Maps to the MAX-ACCESS element of SNMP MIB definition, Version 2.

Status

Maps to the STATUS element of SNMP MIB definition, Version 2.

Explanation

Describes the function, use and precise derivation of the variable. (For example, a variable might be derived from a particular configuration file parameter or performance table field.) When appropriate, incorporates the DESCRIPTION part of the MIB definition, Version 2.

Typical Range

Describes the typical, rather than theoretical, range of the variable. For example, while integer values for many MIB variables can theoretically range up to 4294967295, a typical range in an actual installation will vary to a lesser extent. On the other hand, some variable values for a large database can actually exceed this "theoretical" limit (a "wraparound"). Specifying that a variable value typically ranges from 0 to 1,000 or 1,000 to 3 billion will help the third-party developer to develop the most useful graphical display for the variable.

Significance

Describes the significance of the variable when monitoring a typical installation. Alternative ratings are Very Important, Important, Less Important, or Not Normally Used. Clearly, the DBA will want to monitor some variables more closely than others. However, which variables fall into this category can vary from installation to installation, depending on the application, the size of the database, and on the DBA's objectives. Nevertheless, assessing a variable's significance relative to the other variables in the MIB can help third-party developers focus their efforts on those variables of most interest to the most DBAs.

Related Variables

Lists other variables in this MIB, or other MIBs implemented by Oracle, that relate in some way to this variable. For example, the value of this variable might derive from that of another MIB variable. Or perhaps the value of this variable varies inversely to that of another variable. Knowing this information, third-party developers can develop useful graphic displays of related MIB variables.

Suggested Presentation

Suggests how this variable can be presented most usefully to the DBA using the management application: as a simple value, as a gauge, or as an alarm, for example.