Plugin Monitors

The plugin monitor functionality in Helix allows creating new monitors in Java or any other programming language such as C, perl, shell, etc. The system treats such plugin monitors as an integrated component of Helix and provides a similar multi-threaded framework as it uses internally for its own monitors.

Each plugin monitor has an associated XML configuration file describing the test type, default thresholds and various display parameters. The configuration files are installed in the HELIX_HOME/plugin/monitors/ directory and the actual plugin monitor file is installed in a subdirectory under the plugin/monitors directory. The name of the subdirectory must match the monitor type specified in the configuration file.

12.2 Adding A New Test Type

Each test configured in Helix is assigned a type and sub-type. The test type and sub-type combination serve as the key for global default information that is read from various configuration files. If Helix is unable to locate the configuration information for a particular test type and sub-type, it will be ignored (with an error message logged). Such configuration information is loaded from HELIX_HOME/etc/TestTypes.xml and other plugin configuration files (described in the sections that follow).

When creating new (plugin) monitors, you will need to create a unique test type and sub-type for that monitor and provide various default values and other parameters. The entries in HELIX_HOME/etc/TestTypes.xml or other directories should not be edited (unless you are instructed to edit them by Fidelia support) as it may adversely affect or cause failure of Helix components. Any changes made to these directories may also be lost when a new version of Helix is installed. All user customizations are expected to placed in HELIX_HOME/plugin and its subdirectories.

<testtype> 
		<displayName>Current Temperature</displayName>
		<displayCategory>application</displayCategory>
		<subType>temperature</subType>
		<units>degrees C</units>
		<severityAscendsWithValue>true</severityAscendsWithValue>
		<defaultWarningThreshold>100</defaultWarningThreshold>
		<defaultCriticalThreshold>120</defaultCriticalThreshold>
		<shadowWarningThreshold>100</shadowWarningThreshold>
		<shadowCriticalThreshold>120</shadowCriticalThreshold>
		<slaThreshold>120</slaThreshold>
		<testInterval>180</testInterval>
		<showAsGroup>true</showAsGroup> 
		<testField>
			<fieldName>city</fieldName>
			<fieldDisplayName>City</fieldDisplayName>
			<isRequired>true</isRequired>
			<isPassword>false</isPassword>
			<defaultValue>Muskogee</defaultValue>
		</testField> 
		<testField>
			<fieldName>state</fieldName>
			<fieldDisplayName>State/Province</fieldDisplayName>
			<isRequired>true</isRequired>
			<isPassword>false</isPassword>
			<defaultValue>OK</defaultValue>
		</testField> 
		<testField>
			<fieldName>country</fieldName>
			<fieldDisplayName>Country</fieldDisplayName>
			<isRequired>true</isRequired>
			<isPassword>false</isPassword>
			<defaultValue>US</defaultValue>
		</testField> 
</testtype>

XML TestType element
child element	description
`displayName`	A user-friendly name that is used when creating a report or referring to a specific testtype
`displayCategory`	This setting defines the column that the test result should be in on the summary pages in the web application. Valid values are `network`, `system`, and `application`.
`subType`	This is a string that uniquely identifies the testtype to the Helix software. You can choose whatever string you want, with some restrictions. The subtype must be unique to the monitor that the test is running on, and can only contain alphanumeric characters.
`units`	The units for the test measurement. This will be used in reports and event and summary displays. If the particular test does not have a suitable unit, use a space as the unit.
`severityAscendsWithValue`	This is used to indicate a severity direction for test values, and has two valid values: `true` or `false`. If `severityAscendsWithValue` is `true`, then the status property being tested is becoming worse as the test value rises. When the value is `false`, this indicates that the property status is becoming worse as the test value drops.
`defaultWarningThreshold`	This is the default end-user warning threshold for this test type.
`defaultCriticalThreshold`	This is the default end-user critical threshold for this test type.
showAsGroup	Group tests of the same sub-type together in the web app during autoDiscovery of SNMP tests for a device.
`shadowWarningThreshold`	The default admin warning threshold for this test type. Typically this value will be same as `defaultWarningThreshold`.
`shadowCriticalThreshold`	The default admin critical threshold for this test type. Typically this value will be same as `defaultCriticalThreshold`.
`slaThreshold`	The default SLA threshold for this test type.
`testInterval`	The default interval, in seconds, for running this test.
`testField`	This element defines a specific attribute for the test. A testtype can have 0 or more testfields. Each testfield should have the following child elements: `fieldName` - This will be used as key for the field value when it's passed to the test. `fieldDisplayName` - A user friendly name for the field that will be used by the web application when creating or updating tests. `isRequired` - This element indicates whether or not the a value is required to be given for the field when creating or updating the test. `isPassword` - This indicates whether or not the field is a password field. The web application will ask for verification of password fields when creating or updating a test. `defaultValue` - A default value that will be presented to a user when creating the test.

12.3 Creating A New Plugin Script Monitor

12.3.1 Configuration File Format

Helix uses an XML file to describe settings for script plugin monitors. Here is an example test descriptor that might be used to describe a plugin script that monitors weather information:

The first element is the monitor element. The monitor element defines what monitor the different tests belong to. There are two attributes for the monitor element:

attribute	description
type	This defines a type name for the plugin, and the type of monitoring it does. The value of type will show up in the DGE status line when displaying the testing queues and monitor status, and will be used in the web application
plugintype	This attribute describes the type of plugin. For a script plugin monitor, this parameter should be set to `script`.

The second element is the script element. This element describes the way the script should be run. The script element has two attributes, type and subType, that will associate the script with a test type. The type attribute for the script should have the same value as the type attribute of the monitor element. In this case, they're both weather. The value of the subType attribute should match the subType attribute of one of the testType elements owned by the monitor. Our script will get the temperature, so we want it to be associated with the temperature test type, so we give its subType the same value, temperature, as the subType for the temperature test type.

The next two child elements are fairly straightforward. The rootScript element gives the name of the script to run, and the timeout element gives the maximum number of seconds to wait for the script. You should give a timeout of less than 60 seconds for your script, so that the Helix monitor running your script can return in a timely manner if your script hangs for some reason. Timeout values of zero or less will be interpreted as a 60-second timeout.

The final child element is the parameters element, which defines how arguments are passed to the script. You can enter any text for the parameters object, and you can also use testField placeholders to indicate where testField values should be passed. To use a placeholder, simply enter ${, followed by the fieldName of a testField for the testtype your script plugin is handling, and end the placeholder with a }.

In addition, the following variables can also be used in the parameters element of the configuration file:

When Helix calls your script, it will replace the placeholders with the values given when a test was provisioned. Based on the example above, if you provisioned a test for London, England, Helix would call the script with the following arguments:

${device_name}	${device_serial_number}
${device_address}	${device_model}
${device_vendor}	${device_type}
${device_snmp_cid}	${device_snmp_version}
${device_location}	${test_name}
${test_serial_number}	${test_user_warning_threshold}
${test_user_critical_threshold}	${test_shadow_warning_ threshold}
${test_shadow_critical_threshold}	${test_sla_threshold}
${test_type}	${test_sub_type}
${test_units}

If you don't provide a parameters element, the script is called without any arguments.

12.3.2 Writing The Plugin Script

You can write your script in any language you want. When called with the set of arguments you defined in the parameters element of your plugin XML file, your script should run a test based on the arguments. If the test was completed successfully, your script should print a zero or a positive integer on standard out that corresponds to the value determined by testing. If your test failed for some reason, you can print one of the following error codes: -1, to indicate that the test failed for an unknown reason, or -2 to indicate that the test failed for a known reason.

You can also pass out debugging or error information from your script. Any lines beginning with the string "DEBUG:" will be logged to the Helix debug log (this log is turned off by default in the typical Helix installation. Contact Helix support for instructions to turn it on.). Any lines beginning with the string "ERROR:" will be logged to the Helix error log.

Once you're done writing your script, you should test it out separately on the command line to be sure it works. Next, place your script in HELIX_HOME/plugin/monitors/<test_type> directory (where <test_type> is the type name specified in the config file. Place the XML test descriptor in HELIX_HOME/plugin/monitors. If Helix is installed in a distributed environment (multiple hosts), the monitor script and configuration file should be installed on each host running Helix. The Web Application and DGE components will need to be restarted before the new monitor is usable.

12.3.3 Provisioning Plugin Tests

The Web Application and DGE components will need to be restarted before the new monitor is usable. When Helix starts, it will scan the monitor plugin directory for XML matching script files. If an XML file has an error in it, a message will be written to the error log, and the XML file will be ignored. Each different XML file results in a separate test queue in the Helix DGE.

To create a plugin test in the web application, choose Create New Advanced Tests from the Manage Tests page. The test settings you defined in the plugin XML file should show up on this page (remember to restart the Web Application and the DGE after editing your XML file). Fill in the form fields, select the Provision? checkbox next to each test you want to provision, and click the Provision Tests button at the bottom of the page. You should be able to update or delete your newly created plugin tests in the same manner you update and delete the other test.