Skip to content

Check example

Overview

Monitors the relative humidity reported by a sensor endpoint and the rate at which the host receives data, measured between two consecutive check runs. Alerts when the humidity exceeds the warning or critical threshold. Items can be filtered by name or by regular expression. Supports extended reporting via --lengthy.

This plugin is the skeleton for new check plugins. It demonstrates the standard patterns and library functions, from parameter handling and error handling to rate calculation, filtering, table output, perfdata and the Grafana dashboard.

Important Notes:

  • On the first run, returns "Waiting for more data." until at least two measurements are available
  • After a system reboot, counter values may be lower than the previous measurement. The check detects this (negative delta) and returns "Waiting for more data." until the next valid measurement pair

Data Collection:

  • Fetches the data from the endpoint given by --url, handing every transport option the plugin offers (--insecure, --no-proxy, --proxy, --timeout) to the library. A parameter that is declared but never forwarded looks like it works and silently does not, which is the mistake this skeleton is meant to keep you from making
  • Items can be filtered by --name (exact match), limited with --match and excluded with --ignore (case-sensitive Python regular expressions; use (?i) for case-insensitive matching). An item hit by --ignore is dropped even if it also matches --match
  • Uses SQLite state persistence between runs to calculate deltas (e.g. bytes per second)

Fact Sheet

Fact Value
Check Plugin Download https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/example
Nagios/Icinga Check Name check_example
Check Interval Recommendation Every minute
Can be called without parameters No (--token is required)
Runs on Cross-platform
Compiled for Windows No (runs with Python interpreter)
3rd Party Python modules psutil
Uses State File $TEMP/linuxfabrik-monitoring-plugins-example.db

Help

usage: example [-h] [-V] [--always-ok] [-c CRIT] [--ignore IGNORE]
               [--insecure] [--lengthy] [--match MATCH] [--module MODULE]
               [--name NAME] [--no-match-severity {ok,warn,crit,unknown}]
               [--no-perfdata] [--no-proxy] [--proxy PROXY]
               [--timeout TIMEOUT] --token TOKEN [--url URL] [-w WARN]

Monitors the relative humidity reported by a sensor endpoint and the rate at
which the host receives data, measured between two consecutive check runs.
Alerts when the humidity exceeds the warning or critical threshold. Items can
be filtered by name or by regular expression. Supports extended reporting via
--lengthy.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --always-ok           Always returns OK.
  -c, --critical CRIT   CRIT threshold in percent. Supports Nagios ranges.
                        Default: 90
  --ignore IGNORE       Any item matching this Python regex will be ignored.
                        Can be specified multiple times. Example:
                        `(?i)linuxfabrik` for a case-insensitive match.
  --insecure            This option explicitly allows insecure SSL
                        connections.
  --lengthy             Extended reporting.
  --match MATCH         Filter by this Python regular expression. Case-
                        sensitive by default; use `(?i)` for case-insensitive
                        matching. Can be specified multiple times. If both
                        `--match` and `--ignore` are given, an item must match
                        `--match` AND not match `--ignore` to be reported
                        (include first, exclude second). Examples:
                        `(?i)example` to match "example" regardless of case.
                        `^(?!.*example).*$` to match any string except
                        "example" (negative lookahead).
  --module MODULE       "modulename" to check (startswith). Can be specified
                        multiple times. Example: `--module json --module
                        mbstring`.
  --name NAME           Only check items with this name. Can be specified
                        multiple times. If not specified, all items are
                        checked.
  --no-match-severity {ok,warn,crit,unknown}
                        State to report when no item matches the filters and
                        nothing is checked. Default: ok
  --no-perfdata         Suppress the performance data section from the output.
                        The status message and the exit code are unaffected,
                        so alerting keeps working while trending data is
                        dropped.
  --no-proxy            Do not use a proxy, not even one the environment
                        names. Overrides `--proxy`.
  --proxy PROXY         Proxy to reach the target through. The scheme defaults
                        to `http` when omitted. Overrides the proxy the
                        environment names (`http_proxy`, `https_proxy`,
                        `all_proxy`) together with the exceptions it lists in
                        `no_proxy`, and is itself overridden by `--no-proxy`.
                        Without either parameter the environment applies.
                        Credentials belong into the environment variable
                        rather than here, because a command-line argument is
                        visible to every user on the host. Example:
                        `--proxy=http://proxy.example.com:3128`.
  --timeout TIMEOUT     Network timeout in seconds. Default: 8 (seconds)
  --token TOKEN         Software API token.
  --url URL             URL to the endpoint. Default: http://localhost
  -w, --warning WARN    WARN threshold in percent. Supports Nagios ranges.
                        Default: 80

Documentation:
https://linuxfabrik.github.io/monitoring-plugins/check-plugins/example/

Usage Examples

./example --token=linuxfabrik --warning=80 --critical=90

Output (first run):

Waiting for more data.

Output (subsequent runs):

42% humidity, up 1D 10h since 2026-09-17 01:33:43, 1.2MiB/s, 42K items

Title     ! Value
----------+------
humidity1 ! 42%

With --lengthy:

42% humidity, up 1D 10h since 2026-09-17 01:33:43, 1.2MiB/s, 42K items

Title     ! Type  ! Value
----------+-------+------
humidity1 ! Lorem ! 42%

States

  • OK if the percentage value is below the warning threshold.
  • OK with "Waiting for more data." on the first run or after a reboot.
  • WARN if the percentage value is >= --warning (default: 80).
  • CRIT if the percentage value is >= --critical (default: 90).
  • OK with "Nothing checked." if the filters match no item.
  • UNKNOWN on missing Python modules, invalid --match or --ignore patterns, or invalid command-line arguments.
  • --no-match-severity sets the state reported when the filters match no item and nothing is checked (default: ok); set it to warn, crit, or unknown to alert on an empty selection (for example a filter typo or a missing item) instead of silently returning OK.
  • --always-ok suppresses all alerts and always returns OK.

Perfdata / Metrics

Name Type Description
humidity Percentage The measured relative humidity.
rx_bytes_per_second Bytes Received bytes per second, calculated as delta between two consecutive check runs.

Troubleshooting

Python module "psutil" is not installed.

Install psutil: pip install psutil or dnf install python3-psutil.

Waiting for more data.

This is expected on the first run. The check needs at least two measurements to calculate a delta. Wait for the next check interval.

Invalid --match or --ignore regular expression

A pattern passed via --match or --ignore is not a valid Python regular expression; the plugin reports that it contains one or more errors. Check the syntax at https://docs.python.org/3/library/re.html.

Credits, License