Write scripts for SAM script monitors
Every script monitor accepts code through the Script Body field that you can access by expanding Component Monitor details, as shown in this example of a Linux/Unix Script Monitor included in the OpenLDAP template:
You can develop code against the target system directly in the SAM script monitor or using your preferred scripting environment and programming language, and then copy it into the Script Body field. For example, Microsoft provides a Windows PowerShell Integrated Scripting Environment (ISE). Programming environments and applications give you script libraries and color-coded source code that may be easier to use than the Script Body field.
Use code comments to keep detailed steps and responses in your code. If additional administrators work in the script monitors, the comments provide context for the code. For additional tips, see Script best practices.
Write or copy and paste script code into the Script Body field. Each script monitor includes additional fields and options that may be required to run the scripts. For example, PowerShell includes an arguments field and Nagios includes a command line field. Depending on the programming language and script monitor, you may need to enter the following:
- Hostname and target server information
- Arguments and variables
When ready, test the script to verify credentials and target server access, as well as generate output.
To optimize system performance, create fewer calls by pulling multiple metrics per script. Depending on the load of the calls, you may need to divide the scripts and returned metrics across multiple script monitors.
Script exit codes and output
When a script runs, SAM looks for two main things:
- An exit code that indicates if the script ran successfully. That value is used to report the status of the monitor in the Orion Web Console. For example, to inform SAM that a VBScript reports Up status, exit the script using code similar to the following, where 0 reports Up:
Wscript.quit(0). See Report status through exit codes in SAM script monitors.
- Script output that consists of returned metrics, as described next.
Scripts can also report additional details by sending text to the script’s standard output. See Scripts with text output for details.
For script output, SAM is mainly interested in the 'Statistic:' value followed by a numerical value (for example,
Statistic: 123:). How that information is reported back to SAM and appears in the Orion Web Console depends on the scripting language that you're using.
- For PowerShell scripts, use the Write-Host command.
- For Python, use the Print command.
- For Bash/Shell, use the Echo command.
SAM expects 1 to a maximum of 10 metrics returned with a string of Statistic and a numerical value and an optional message. Each returned metric generates an output. When returning multiple metrics, you can add descriptive labels to the returned statistics, such as
If you exceed the maximum number of allowed output pairs of ten, the remainder above the tenth output pair is ignored.
Note the following details about statistics:
- If using labels for statistics, do not to use spaces.
- If you delete the output, the metric won't appear in the Orion Web Console, but SAM still saves it to the Orion database.
- For Windows scripts, format the Statistic value to use the same decimal separator as the Orion server, as determined by Windows regional settings.