Skip to content

Latest commit

 

History

History
69 lines (59 loc) · 4.41 KB

02.Input.md

File metadata and controls

69 lines (59 loc) · 4.41 KB

Input Parameters for a Monitoring Plugin

A Monitoring Plugin MUST expect input parameters as arguments during execution, if any are needed/expected at all. It MAY accept these parameters given as environment variables and it MAY accept them in a configuration file (with a default path or a path given via arguments or environment variables).

In general positional arguments are strongly discouraged.

Some arguments MUST have this predetermined meaning, if they are used:

Argument (long) Argument (short version, optional) Argument Meaning optional can be given multiple times
--help -h None "Triggers the help functionality of the Monitoring Plugin, showing the individual parameters and their meaning, examples for usage of the Monitoring Plugin and general remarks about the how and why of the Monitoring Plugin. SHOULD overwrite all other options, meaning, they are ignored if --help is given. The Monitoring Plugin SHOULD exit with state UNKNOWN (3). no -- (makes no difference)
--version -V None Shows the version of the Monitoring Plugin to allow users to report errors better and therefore help them and the developers. The Monitoring Plugin SHOULD exit with state UNKNOWN (3). no -- (makes no difference)
--timeout -t Integer (meaning seconds) or a time duration string Sets a limit for the time which a Monitoring Plugin is given to execute. This is there to enforce the abortion of the test and improve the reaction time of the Monitoring System (e.g. in bad network conditions it might be helpful to abort the test prematurely and inform the user about that, than trying forever to do something which won't succeed. Or if soft real time constraints are present, a result might be worthless altogether after some time). A sane default is probably 30 seconds, although this depends heavily on the scenario and should be given a thought during development. If the execution is terminated by this timeout, it should exit with state UNKNOWN (3) and (if possible) give some helpful output in which stage of the execution the timeout occurred. no no
--hostname -H String, meaning either a DNS name, an IPv4 or an IPv6 address of the targeted system If the Monitoring Plugin targets ONE other system on the network, this option should be used to tell it which one. If the Monitoring Plugin does it's test just locally or the logic does not apply to it, this option is, of course, optional. yes yes
--verbose -v None Increases the verbosity of the output, thereby breaking the suggested rules about a short and concise output. Can be used to debug the Monitoring Plugin and should there expose internals, intermediate results and so on. yes yes
--detail None Increases the level of detail in the output, thereby giving the user more information about the result of the test and helping with determining errors and problems or just satisfy some curiosity. SHOULD NOT be used to debug the Monitoring Plugin, so there is no need to expose internals. yes yes
--exit-ok The Monitoring Plugin exits unconditionally with OK (0). Mostly useful for the purpose of packaging and testing plugins, but might be used to always ignore errors (e.g. to just collect data). yes no

Examples

For the execution with --help:

$ my_check_plugin --help

the output might look like this:

my_check_plugin version 3.1.4
Licensed under the AGPLv1.
Repository: git.example.com/jdoe/my_check_plugin

This plugin just says hello. It fails if you don't give it a name.

Usage:
 my_check_plugin --name NAME [--greeting GREETING]

Options:
 --help
   this help
 --version
   Shows the version of the plugin
 --name NAME
   if given, uses NAME as a name to greet.
 --greeting GREETING
   if given, uses GREETING instead of Hello.

Examples:
$ my_check_plugin --name Jane
Hello Jane

$ my_check_plugin --greeting Ciao --name Alice
Ciao Alice

This imaginary Monitoring Plugin tries to be really helpful here, displays the version, the license and the upstream repository with the help (although not necessary), has a short description about the purpose, lists the options in an easily readable way and even gives some examples.

For the execution with --version

$ my_check_plugin --version

the output might be a bit shorter:

my_check_plugin version 3.1.4

or even:

3.1.4

where both show the necessary information.