Oracle Coherence Monitor User Guide

Oracle Coherence Monitor

User Guide

Alert Notification
The OC Monitor provides alerts concerning conditions in a Coherence cluster through RTView alerts.
Information about RTView alerts is available at http://sldownloads.sl.com/docs/rtview/57/user/alerts_intro.html.

There are two techniques for OC Monitor alert notification:

Customize the Java command handler source
This is the default technique because it works on all platforms that support Java. The Java source for the OCM Java command handler is provided to facilitate customization.
Use a batch file or shell script
This technique requires switching to an OS-specific set of alert definitions that execute the appropriate file type. Windows, and UNIX alert definition files are provided with the OCM. A sample batch file and a sample shell script are also provided which are customized as needed.

The default behavior of the Java command handler and scripts is to output alert information to standard output. The alert output appears in the Data Server log file, or in the command window or shell in which the Data Server was started. The following is an output sample from the default Java command handler:

Custom alert command executed
clusterName = DemoCluster
alertName = AvailableMemoryLowNode
alertIndex = OLS-StoreNode-1.SLPRO46
alertId = 1005
alertSeverity = 1
AlertLabel = Low Warning
alertText = Low Warning Limit exceeded, current value: 0.9176470588235294 limit: 0.98

NOTE: OCM alert notifications use the alertCommand property of RTView alert objects. The RTView alert engine automatically populates a set of substitution variables which are passed to an alert command to provide context to alerts as they are triggered. For details regarding alertCommand substitutions, see:
http://sldownloads.sl.com/docs/rtview/57/user/alerts_intro.html#Limits Alerts - Subs
http://sldownloads.sl.com/docs/rtview/57/user/alerts_intro.html#Discrete Alerts - Subs

OCM Alert Command Arguments
The following are substitution variables and scripts that are passed to the OCM Java command handler.

Argument	Description
$clusterName	This substitution contains the name of the Coherence cluster that originated the alert. It is specific to the OCM, and is automatically populated by OCM scripts.
$alertName	These substitutions are a subset of the RTView alertCommand substitutions. They are populated by the RTView alert engine when an alert is triggered. See the links, above, for more information.
$alertIndex
$alertId
$alertSeverity
$alertLabel
$alertText

Alert Command Substitution Values
The values assigned to the alert command substitutions exhibit patterns that can be used to customize Java command handler and script behavior. The following are substitution values as they pertain to the OCM.

Argument Description Values

$alertId This substitution specifies the unique ID for the alert.
For example:
alertId = 1004
Text or Numeric

$alertIndex This substitution specifies which source triggered the alert. With tabular objects, the first column of data is typically the Index column. The value in the Index column is a name that uniquely identifies each table row. The alertIndex uses the Index column name.
For example, if the CapactityLimitAllCaches alert is configured to monitor all of your caches, and to trigger when any of the caches exceed the specified capacity threshold, the alertIndex indicates specifically which cache triggered the alert.

With scalar objects, which do not have a table and therefore do not have a column (the useTabularDataFlag property is False), the alertIndex is blank.

For example:
alertIndex = MyCache01
Text or Numeric

$alertLabel This substitution specifies the alert type. There are two types of alerts, Discrete Alerts and Limits Alerts. The alert values, such as High Alert, indicate which test condition triggered the alert.
Discrete Alerts allow you to compare the input value to up to three test values (one each for low, medium and high alerts), and execute an alert if your input data equals one of these values.

Limits Alerts allow you to compare your input value to a threshold and execute the alert if your input data goes above or below an acceptable range.

For example:
alertLabel = Medium Alert
Discrete Alert Values

High Alert

Medium Alert

Low Alert

Limits Alert Values High Alert

High Warning

Low Alert

Low Warning

$alertName = This substitution specifies the name of the alert.
For example:
alertName = CapacityLimitAllCaches
See the list of OCM alerts.

$alertSeverity This substitution specifies the severity level of the alert.
0: The alert limit has not been exceeded therefore the alert is not activated.
1: The alert warning limit has been exceeded.
2: The alert alarm limit has been exceeded.
For example:
alertSeverity = 1
Numeric

$alertText This substitution specifies the text that is displayed when the alert executes.
For example:
alertText = High Warning Limit exceeded, current value: 0.9452 limit: 0.8
Text

$clusterName This substitution specifies the name of the cluster the alert applies to.
For example:
clusterName = Cluster2
Text or Numeric

Configuring Alert Notification
There are two OC Monitor alert notification options:

Customize the Java command handler source (used by default)
Use a batch file or shell script (for Windows and UNIX/Linux)

Customizing the Java Command Handler
The source for the OC Monitor Java handler is provided in the file MyCommandHandler.java found in the projects/myocm/src/ocm/myclasses directory of the OC Monitor installation. The default behavior of the handler is to print the alert data to standard output. To change this behavior perform the following steps:

1. Open MyCommandHandler.java in a text editor.

2. Modify the OutputAlertString method as needed. You can replace this method with one of your own as long as you modify the invokeCommand method to call it. Your method must accept the same arguments as OutputAlertString.

3. Save MyCommandHandler.java.

4. Compile MyCommandHandler.java and rebuild myclasses.jar using the supplied script (make_myclasses.bat or make_myclasses.sh).

5. Restart the Data Server and perform alert tests as needed.

Using a Batch File or Shell Script
The custom Java command can be replaced with a batch file or shell script to configure alert actions. A sample batch file, my_alert_actions.bat, and a sample shell script, my_alert_actions.sh are provided as templates that can be modified as needed. Use the appropriate file for the platform that hosts OC Monitor processes. By default, both scripts send alert information to standard output. The scripts can be modified as needed.

Windows Batch File
To configure my_alert_actions.bat as the alert command, perform the following steps:

1. Double-click rtvoc_cmd.bat in the OC Monitor installation directory to open a command window.

2. Go to the projects/myocm directory, create a copy of ts_alertdefs_win.rtv and save the file as ts_alertdefs.rtv.

        Example:
        cd projects/myocm
        cp ts_alertdefs_win.rtv ts_alertdefs.rtv

3. Optionally, modify my_alert_actions.bat as needed.

4. Restart the Data Server.

5. To reset the custom Java command as the alert command:

Go to the projects/myocm directory and delete ts_alertdefs.rtv.
Restart the Data Server.

UNIX/Linux
To configure my_alert_actions.sh as the alert command, perform the following steps:

1. Go to the projects/myocm directory, create a copy of ts_alertdefs_unix.rtv and save the file as ts_alertdefs.rtv.

       Example:
       cd $RTVOC_HOME/projects/myocm
       cp ts_alertdefs_unix.rtv ts_alertdefs.rtv

2. Optionally, modify my_alert_actions.sh as needed.

3. Restart the Data Server.

4. To reset the custom Java command as the alert command:

Go to the projects/myocm directory and delete ts_alertdefs.rtv.
Restart the Data Server.

Additional Information
Additional information about RTView commands is available at:

http://sldownloads.sl.com/docs/rtview/57/user/bobj_cmd.html

The standard RTView documentation for alerts is available at:
http://sldownloads.sl.com/docs/rtview/57/user/alerts_intro.html

RTView contains components licensed under the Apache License Version 2.0.

JMS, JMX and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. They are mentioned in this document for identification purposes only.

SL, SL-GMS, GMS, RTView, SL Corporation, and the SL logo are trademarks or registered trademarks of Sherrill-Lubinski Corporation in the United States and other countries. Copyright © 1998-2011 Sherrill-Lubinski Corporation. All Rights Reserved.

Argument	Description	Values
$alertId	This substitution specifies the unique ID for the alert. For example: alertId = 1004	Text or Numeric
$alertIndex	This substitution specifies which source triggered the alert. With tabular objects, the first column of data is typically the Index column. The value in the Index column is a name that uniquely identifies each table row. The alertIndex uses the Index column name. For example, if the CapactityLimitAllCaches alert is configured to monitor all of your caches, and to trigger when any of the caches exceed the specified capacity threshold, the alertIndex indicates specifically which cache triggered the alert. With scalar objects, which do not have a table and therefore do not have a column (the useTabularDataFlag property is False), the alertIndex is blank. For example: alertIndex = MyCache01	Text or Numeric
$alertLabel	This substitution specifies the alert type. There are two types of alerts, Discrete Alerts and Limits Alerts. The alert values, such as High Alert, indicate which test condition triggered the alert. Discrete Alerts allow you to compare the input value to up to three test values (one each for low, medium and high alerts), and execute an alert if your input data equals one of these values. Limits Alerts allow you to compare your input value to a threshold and execute the alert if your input data goes above or below an acceptable range. For example: alertLabel = Medium Alert	Discrete Alert Values	High Alert
			Medium Alert
			Low Alert
		Limits Alert Values	High Alert
			High Warning
			Low Alert
			Low Warning
$alertName =	This substitution specifies the name of the alert. For example: alertName = CapacityLimitAllCaches	See the list of OCM alerts.
$alertSeverity	This substitution specifies the severity level of the alert. 0: The alert limit has not been exceeded therefore the alert is not activated. 1: The alert warning limit has been exceeded. 2: The alert alarm limit has been exceeded. For example: alertSeverity = 1	Numeric
$alertText	This substitution specifies the text that is displayed when the alert executes. For example: alertText = High Warning Limit exceeded, current value: 0.9452 limit: 0.8	Text
$clusterName	This substitution specifies the name of the cluster the alert applies to. For example: clusterName = Cluster2	Text or Numeric