Introduction to plugins

Overview

A plugin is a small executable that takes optional command line parameters as input and performs the following:

  • Performs a test.
  • Reports a diagnostic message in the OP5 Monitor user interface.
  • Returns an exit code.

Plugins are used by OP5 Monitor to run the check commands at the core of its monitoring functionality.

Plugins delivered with OP5 Monitor

OP5 Monitor is delivered with a standard set of frequently used plugins, in default plugin directory /opt/plugins.

Note: The Slim Poller does not include all the plugins delivered with OP5 Monitor.

You can view the list of plugins in OP5 Monitor by clicking Manage > Configure > Plugins. Each plugin is listed with its support level. You can expand a plugin to see its details, and click any of the command links to go to the command configuration page, where you can view the command arguments and other details.

For a reference of the standard OP5 Monitor plugins, see Plugin reference.

Plugin support levels

The table below describes the support levels available for plugins.

Icon Name Level of Support Explanation

Full Level 4 (high and fully supported) ITRS fully supports and continuously tests this plugin. We have a fully compatible test environment to verify its functionality.

Bug Support Level 5 (medium and bug support) ITRS does not test this plugin continuously. We may not have a compatible test environment available, as that may require resources beyond demand. If we or you discover a defect with the plugin, we will examine its importance and give it a priority based on its customer impact as well as the necessary developer effort. ITRS monitors its upstream project (if there is one) and updates the shipped plugin regularly.

Best Effort Level 6 (low and best effort) ITRS ships this plugin only as a courtesy to our customers. At some point in the plugin's history, we or a trusted customer made sure that dependencies resolved and that the plugin executed without runtime errors. The plugin has normally only been installed and tested at a customer site. ITRS can help out with command syntax.

Deprecated Level 8 (deprecated) ITRS has concluded that this plugin can no longer be supported. It may have been replaced by a newer plugin, which we will name in the top line of its comments. Please review the specific details so you can plan your changeover.

Unsupported None ITRS does not support this plugin.

Information returned by plugins

Return codes

The return code of a plugin is used by OP5 Monitor to determine the state a of service. It can be any of the following: 0, 1, 2, 3

Any return code above 0 indicates a problem state.

The table below explains the meanings of different return codes.

Number Description
0 OK — the check went well and everything seems to be working fine.
1 Warning — the plugin was able to check the service, but it appeared to be above some warning threshold or did not appear to be working properly.
2 Critical — the plugin detected that either the service was not running or it was above some critical threshold.
3 Unknown — something unknown happened during the check. Invalid command line arguments or low-level failures internal to the plugin are not reported as unknown.

Status information

The status information is the text describing the result in human readable form. The plugin must print the status output to stdout when your plugin is executed.

You can find the status information on the service or host detail page:

The text can be anything you want to use to describe the status situation for your plugin, including HTML.

Performance data

The plugin displays the performance data result in numbers. It is not mandatory to include performance data in responses, but the data is used to produce performance graphs in OP5 Monitor, so you must include it if you want to produce graphs from your plugin. You configure the performance data as follows:

'label'=value[UOM];[warn];[crit];[min];[max]
Part Description

label

The label can contain any characters. If it includes spaces you need quotes.

value

The performance data number value.

UOM

Unit of measurement of the performance data value. Can be any of the following:

  • no unit, assuming an integer as a value.
  • s — seconds, also us, ms.
  • % — percentage.
  • B — bytes (also KB, MB, GB and TB).
  • c — a continuous counter, such as bytes transmitted in an interface.

warn, crit, min, max

Performance state.

  • Can all be null and trailing semicolons can be dropped.
  • min and max is not needed if UOM is %.
  • value, warn, crit, min and max must have the same UOM.

Example performance data output

The following example shows performance data output from a plugin with two values separated by one space:

time=0.218901s;;;0.000000 size=42236B;;;0

Example

This example executes the check_tcp plugin to test ports 80 and 143 on IP address 193.201.96.136:

# /opt/plugins/check_tcp -H 193.201.96.136 -p 80
TCP OK - 0.043 second response time on port 80|time=0.042824s;0.000000;0.000000;0.000000;10.000000
# echo $?
0
# /opt/plugins/check_tcp -H 193.201.96.136 -p 143
Connection refused
# echo $?
2

Port 80/tcp sends a response, so the plugin returns a success exit code of 0. It also returns a response output with two parts divided by a | sign (pipe). The text on the left of the pipe is the status information, and the text on the right is the performance data.

Port 143/tcp on the same host is not open, so the plugin returns a critical exit code of 2.