Using a scripting language of your choice, create a script that contains logic to check for the condition being monitored. For example, scripts that check for disk space or memory usage. All scripts to be run with user-defined metrics should be placed in a directory to which the Management Agent has full access privileges. Scripts themselves must have the requisite permissions set so that they can be executed by the Management Agent. The script runtime environment must also be configured: If your script requires an interpreter, such as a Perl interpreter, this must be installed on that host as well.
All monitoring scripts should contain code to perform the following basic functions:
Define logic in the code that checks the condition being monitored. For example, determining the amount of free space on a particular filesystem or level of memory usage.
After checking the monitored condition, the script should return the value associated with the monitored object.
If you choose to have the script return a specific value from the monitored object (e.g. current disk space usage), this means you want Enterprise Manager to evaluate the object's current value against specific warning and critical thresholds. You specify these warning and critical thresholds from the Console at the time you create the user-defined metric. Based on the evaluation of the metric’s value against the thresholds, an alert may be triggered at one of the following severity levels:
Alert Severity Levels
Severity Level |
Status |
|---|---|
| Script Failure | The script failed to run properly. |
| Clear | No problems with the object monitored; status is clear. If thresholds were specified for the metric, then it means the thresholds were not reached. |
| Warning | The value of the monitored object reached the warning threshold. |
| Critical | The value of the monitored object reached the critical threshold. |
After evaluating the status of the monitored object, the script needs to return this result to Enterprise Manager. The script should return the result by sending formatted information to standard output (stdout) using the syntax that is consistent with the scripting language (PRINT, for example).
Enterprise Manager checks the standard output of a script for two recognizable tags: em_result and em_message.
The output of the script execution must provide the result in the following format in order for Enterprise Manager to determine if the script executed successfully or if it had failed. The output must be written as string delimited by new line characters.
For example
em_result=<some value>\n
em_message=<some message>\n
Important: Script output tags must be lower-case in order for Enterprise Manager to recognize the script output as valid user-defined metric feedback. Messages or values associated with each tag can be mixed case.
Valid tag output: em_result=My Value\n
Invalid tag output: Em_Result=My Value\n
For a successful script execution, the script output must start with the "em_result=" string in a new line. The message must start with the "em_message=" string in a new line.
The following table summarizes the script output tags.
Script Output Information Tags
Tag |
Definition |
|---|---|
| em_result | Use this tag to return script result values. Exactly one em_result
tag must be found in STDOUT. If more than one em_result tag is found,
the first tag encountered will be used; subsequent em_result tags will
be ignored.
Example: print "em_result=200\n"
|
| em_message | Use this tag to specify a message with the script result value in STDOUT.
For OS-based user-defined metrics, only one em_message tag is permitted.
If you submit more than one em_message tag, only the first tag is used;
subsequent tags are ignored.
Example: print "em_result=200\nem_message=Disk usage is high\n"Returns 200 as the value of the monitored object in addition to the message "Disk usage is high". If script execution is successful AND it does not contain a em_message string, a default em_message string is automatically generated. The following message format is used: em_message=The value is $em_resultExample: print "em_result=200\n"Returns 200 as the value of the monitored object and the generated message "The value is 200" |
The output of the user-defined monitoring script must be em_result and em_message.
Important: The monitoring script must be located on the same machine where an Enterprise Manager Management Agent resides. The machine must be monitored by an Enterprise Manager Management Agent. Make sure the machine has the script's runtime requirements (such as a Perl interpreter if you are running Perl scripts) and that the script is able to run independently of Enterprise Manager.
When the user-defined metric is evaluated, it executes the script using the credentials (user name and password) specified at the time the user-defined metric was registered in the Enterprise Manager Console. Ensure that the user name and password you specify for the user-defined metric is an active account (on that machine) possessing the requisite permissions to run the script.
You can use Enterprise Manager's Monitoring Template feature to deploy user-defined metrics. Templates allow you to specify metric settings once and apply those settings to any number of targets.
Deploying User-Defined Metrics Across Large Numbers of Targetss
Registering the Script as a User-Defined Metric
Enterprise Manager Information Roadmap
Copyright © 1996, 2007, Oracle. All rights reserved.