| 1 | # scripts.d.plugin (preview) |
| 2 | |
| 3 | `scripts.d.plugin` runs Nagios-style check scripts inside Netdata without changing |
| 4 | plugin output format. The active collector is `nagios` (single collector surface), |
| 5 | implemented as a normal V2 collector with collector-local scheduling/state. |
| 6 | |
| 7 | > **Status:** preview. Core execution, retry/state tracking, and perfdata routing are |
| 8 | > implemented; config/docs may still evolve. |
| 9 | |
| 10 | ## Configuration |
| 11 | |
| 12 | - Plugin-level toggles: `/etc/netdata/scripts.d.conf` |
| 13 | - Collector jobs: `/etc/netdata/scripts.d/nagios.conf` |
| 14 | |
| 15 | Each job is a Nagios check definition. |
| 16 | |
| 17 | Example: |
| 18 | |
| 19 | ```yaml |
| 20 | jobs: |
| 21 | - name: ping_localhost |
| 22 | plugin: "/usr/lib/nagios/plugins/check_ping" |
| 23 | args: ["-H", "127.0.0.1", "-w", "100.0,20%", "-c", "200.0,40%"] |
| 24 | timeout: 5s |
| 25 | check_interval: 1m |
| 26 | retry_interval: 30s |
| 27 | max_check_attempts: 3 |
| 28 | ``` |
| 29 | |
| 30 | The `plugin` value must be an absolute path. If you need an interpreter, point |
| 31 | `plugin` to the interpreter executable and pass the script path in `args`. |
| 32 | |
| 33 | ### Time Periods |
| 34 | |
| 35 | `check_period` is supported. Custom periods are defined with `time_periods` inside |
| 36 | the same job definition. |
| 37 | |
| 38 | ```yaml |
| 39 | jobs: |
| 40 | - name: local_plugins |
| 41 | plugin: "/usr/lib/nagios/plugins/check_dummy" |
| 42 | args: ["0", "ok"] |
| 43 | check_period: 24x7 |
| 44 | time_periods: |
| 45 | - name: 24x7 |
| 46 | alias: Always on |
| 47 | rules: |
| 48 | - type: weekly |
| 49 | days: [sunday, monday, tuesday, wednesday, thursday, friday, saturday] |
| 50 | ranges: ["00:00-24:00"] |
| 51 | ``` |
| 52 | |
| 53 | ## Writing Compatible Checks |
| 54 | |
| 55 | A compatible check returns a Nagios state with its exit code and prints a status |
| 56 | line that Netdata can parse. |
| 57 | |
| 58 | - Exit codes: |
| 59 | - `0` = OK |
| 60 | - `1` = WARNING |
| 61 | - `2` = CRITICAL |
| 62 | - `3` = UNKNOWN |
| 63 | - First-line output format: |
| 64 | - `<summary text> | <perfdata>` |
| 65 | - The `|` separator is optional: |
| 66 | - text before `|` is the human-readable summary |
| 67 | - text after `|` is performance data used for auto-generated charts |
| 68 | - Each performance-data item follows: |
| 69 | - `'label'=value[UOM];warn;crit;min;max` |
| 70 | - Separate multiple metrics with spaces. |
| 71 | - Common units include: |
| 72 | - `%`, `s`, `ms`, `B`, `KB`, `MB`, `GB`, `c` |
| 73 | - If the script prints multiple lines: |
| 74 | - the first line is the summary |
| 75 | - the remaining lines are kept as long output |
| 76 | |
| 77 | Minimal example: |
| 78 | |
| 79 | ```bash |
| 80 | #!/bin/sh |
| 81 | echo "CPU OK - 20% used | cpu=20%;80;90" |
| 82 | exit 0 |
| 83 | ``` |
| 84 | |
| 85 | ## Execution Model |
| 86 | |
| 87 | - Each `jobs:` entry becomes one V2 Nagios collector instance. |
| 88 | - Script execution happens during `Collect()` only when the job is due. |
| 89 | - `update_every` is the scheduling resolution. |
| 90 | - If `update_every` is slower than `check_interval` or `retry_interval`, Netdata |
| 91 | logs a warning and the effective cadence is limited by `update_every`. |
| 92 | - Nagios semantics are preserved collector-side: |
| 93 | - `check_interval` |
| 94 | - `retry_interval` |
| 95 | - `max_check_attempts` |
| 96 | - `check_period` |
| 97 | - If a check exceeds `timeout`, Netdata reports the job state as `timeout`. |
| 98 | - If a check is due but the current time is outside `check_period`, Netdata does not execute it and reports the public job state as `paused`. |
| 99 | - Non-due successful cycles replay the last cached perfdata values and threshold |
| 100 | states so chartengine series stay alive between executions. |
| 101 | - When a due run is blocked by `check_period`, perfdata value charts remain at their last observed values, but threshold-state charts are zeroed until the next successful execution. |
| 102 | - Counter perfdata keeps counter semantics for the value series. Replayed raw |
| 103 | totals naturally flatten to zero deltas between executions. |
| 104 | |
| 105 | Defaults: |
| 106 | |
| 107 | - `check_interval`: `5m` |
| 108 | - `retry_interval`: `1m` |
| 109 | - `timeout`: `5s` |
| 110 | - `max_check_attempts`: `3` |
| 111 | |
| 112 | ## Metrics and Charts |
| 113 | |
| 114 | Static template charts: |
| 115 | |
| 116 | - `nagios.job.execution_state` |
| 117 | - `nagios.job.perfdata_threshold_state` |
| 118 | - `nagios.job.execution_duration` |
| 119 | - `nagios.job.execution_cpu` |
| 120 | - `nagios.job.execution_memory` |
| 121 | |
| 122 | Perfdata is routed plugin-side and materialized via autogen: |
| 123 | |
| 124 | - Unit classes: `time`, `bytes`, `bits`, `percent`, `counter`, `generic` |
| 125 | - Metric identity: sanitized perfdata key (from Nagios perfdata label) |
| 126 | - Unit-class changes create a new metric identity |
| 127 | - Collision policy: deterministic keep-first, drop conflicting label |
| 128 | - Per-job metric count is capped by the collector budget before emission |
| 129 | - Each perfdata metric creates one value chart. |
| 130 | - Non-counter perfdata also creates: |
| 131 | - one plugin-scoped derived threshold-state chart for visualization |
| 132 | - one static `nagios.job.perfdata.threshold_state` duplicate for alerting, labeled by `perfdata_value=<class>_<metricKey>` |
| 133 | - Threshold-state values are: |
| 134 | - `no_threshold` |
| 135 | - `ok` |
| 136 | - `warning` |
| 137 | - `critical` |
| 138 | - Counter perfdata currently does not emit a threshold-state chart. |
| 139 | - Raw `min`, `max`, and raw threshold bounds are not charted. |
| 140 | |
| 141 | ## Alerts |
| 142 | |
| 143 | - Built-in Netdata health alerts are shipped for: |
| 144 | - `nagios.job.execution_state` |
| 145 | - `nagios.job.perfdata_threshold_state` |
| 146 | - `nagios.job.execution_state` is a bitset chart. It always exposes the current |
| 147 | primary state and also exposes `retry=1` while a non-OK result is still |
| 148 | retrying. |
| 149 | - `nagios.job.perfdata_threshold_state` is also a bitset chart. It exposes the |
| 150 | current non-counter perfdata threshold state and also exposes `retry=1` while |
| 151 | that threshold result comes from a retrying soft run. |
| 152 | - Stock alerts cover only the `warning` and `critical` states and suppress |
| 153 | retrying soft states on both built-in alert contexts. |
| 154 | - If you want alerts for `unknown`, `timeout`, `paused`, or custom perfdata |
| 155 | alerting rules, use these contexts as the base for your own rules. |
| 156 | |
| 157 | ## Logging |
| 158 | |
| 159 | Checks log through the collector/job logger path. There is no separate public runtime |
| 160 | component or scheduler telemetry surface. |
| 161 | |
| 162 | ## Windows Note |
| 163 | |
| 164 | - On Windows, the collector runs the command named in `plugin` directly. |
| 165 | - Use an executable path, or point `plugin` to an interpreter such as |
| 166 | `powershell.exe` and pass the script path in `args`. |
| 167 | |
| 168 | ## Tests |
| 169 | |
| 170 | ```bash |
| 171 | cd src/go |
| 172 | go test ./plugin/scripts.d/collector/nagios/... -count=1 |
| 173 | ``` |
| 174 | |
| 175 | ## Build |
| 176 | |
| 177 | ```bash |
| 178 | cmake -DENABLE_PLUGIN_SCRIPTS=On .. |
| 179 | cmake --build . --target scripts-plugin |
| 180 | ``` |
| 181 | |
| 182 | Binary path: |
| 183 | |
| 184 | - `usr/libexec/netdata/plugins.d/scripts.d.plugin` |
| 185 | |
| 186 | Stock config path: |
| 187 | |
| 188 | - `usr/lib/netdata/conf.d/scripts.d/` |