OP5 Monitor ["OP5 Monitor"]
["Technical Reference"]

# 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`.

Was this topic helpful?
Your thoughts...
How can we improve this topic?
It did not answer my question(s)
Confusing
Missing screenshot or graphics
Missing technical details
Information is out of date
Your thoughts...
Thank you for your feedback!