Script Service

Topics marked with * relate to features available only in vFabric Hyperic.

Script Service Overview

You can configure Hyperic to run a custom measurement script on a scheduled basis and save metrics in in the Hyperic database along with plugin-reported metrics. To integrate a custom script, you create a platform service of type "Script", and define the script location and any arguments on the Configuration Properties page for the service. If your script returns results, the first value in the result stream is reported as a "Result Value" metric.

Hyperic Support for Nagios Script-Based Monitoring

Hyperic has built-in support for Nagios integration. If you use Nagios, note that you can configure Hyperic to run Nagios checks and store the results in the Hyperic database. For more information, see Nagios.

About Custom Script Plugins

If you wish to run scripts in Hyperic that provide richer monitoring than available from a configured script service, you can build a custom script plugin that reports as many metrics as you likc. A script plugin includes an XML descriptor and at least one script, which can be defined externally or embedded in the XML file. The plugin can use multiple scripts or a single script; the script must output key=value pairs. For more information, see Script Plugins in vFabric Hyperic Product Plugin Development.

Unicode characters must be escaped

Unicode characters encountered in a script will be decoded during script processing. For example, the string "%3D" is decoded to an equals sign (=). To preserve the value of s string that might be interpreted as a Unicode character, escape the string with a double backslash, for example:

\\%3D

Create Script Service in Hyperic

To create a script service.

  1. Navigate to the platform where the script runs.

  2. Select New Platform Service from the Tools menu. 

  3. Name the script.

  4. Select "Script" from the Service Type pull-down.

  5. Click Edit in the "Configuration Properties" section of the new service's Inventory page.

  6. On the Configuration Properties page, supply at least the required properties, described in the table below.

Script Service Configuration Options

Name

Description

Required

Example

Notes

prefix

Space delimited prefix argument(s)

No

sudo

path

Path to the script or program

Yes

/usr/local/nagios/libexec/check_http

HQ will check that the path exists

arguments

Space delimited script arguments

No

-H 209.237.227.36

Use quotes for arguments with spaces

timeout

Timeout in seconds

Yes

120

Execution is aborted if > timeout

Script Service Metrics

Each instance of a Script service provides the following metrics:

  • Availability — Uses process exit code:

    • 0 == images/download/attachments/79038082/icon_available_green0.gif OK

    • 1 == images/download/attachments/79038082/icon_available_yellow0.gif Warning

    • 2 == images/download/attachments/79038082/icon_available_red0.gif Critical

    • 3 == images/download/attachments/79038082/icon_available_error0.gif Unknown

    • 4 == images/download/attachments/79038082/icon_available_orange0.gif Paused

  • Execution Time — Milliseconds it took to execute the script

  • Result Value — If the script returns results, the first result in the output stream, for example:
    "Number of Transactions: 234"

Event Tracking

You can enable log tracking for a script service. If you do, the agent will log an event for responses that match the criteria you specify.

To enable log tracking, click the Enable Log Tracking box in the Monitoring section of the Configuration Properties page.

For information about Hyperic log tracking functionality and configuration options, and how to view log events, see Set Up Log Tracking for a Resource.