custom

Watch: custom

watch.custom lets the collector judge by itself, with settings the administrator changes on the probe: here, the status file of a backup tool, too old, ended badly or too small.

How to read it

• watch.custom('backup', 'Backup not good', array('help' => …, 'settings' => …)): no output, since the code judges. The help sentence is required: nothing else describes what the watch does.
• Each setting has a label, a form and a default: here duration ('1 d'), text and number (with a unit).
• watch.setting('backup', 'max-age') reads the setting as the probe holds it: a number of seconds for a duration, a number, a text; '' when the administrator left it empty. The code tests != '' before using it.
• A fourth form, names, holds a list. It is left out of this example on purpose: a list left empty also reads '', and what comparing a list with '' gives is not settled yet in Keen 1.0.0. The accepted result is therefore one text.
• watch.raise('backup', 'critical', 'last backup 30 h ago') raises the watch, with the sentence the administrator reads. It can name an element as a fourth argument, for a collector with per. Raised twice, the gravest level wins.
• A watch the probe does not check is never raised, whatever the code does.

To adapt it

• Use custom only when no other kind says it: an age, a threshold or a list are often a plain above, below or expect on an output.
• The status file here is an invention of the example: write the path and the format of the tool you use.