@cryptotaxi247 / netdata-1 / commits / dc699d88f

Regenerate integrations docs (#22015)

Co-authored-by: stelfrag <52996999+stelfrag@users.noreply.github.com>

Netdata bot committed Mar 23, 2026 at 13:18 UTC dc699d88fe5ac46715b40118662d0dd731a6d557

2 files changed +243 -86

src/collectors/COLLECTORS.md

+1 -1

@@ -575,7 +575,7 @@ Need a dedicated integration? [Submit a feature request](https://github.com/netd

575 | [IOPing](https://github.com/netdata/netdata/blob/master/src/collectors/ioping.plugin/integrations/ioping.md) | Monitor IOPing metrics for efficient disk I/O latency tracking. |

576 | [Monit](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/monit/integrations/monit.md) | This collector monitors status of Monit's service checks. |

577 | [MQTT Blackbox](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/prometheus/integrations/mqtt_blackbox.md) | Track MQTT message transport performance using blackbox testing methods. |

578 -| [Nagios Plugins](https://github.com/netdata/netdata/blob/master/src/go/plugin/scripts.d/collector/nagios/integrations/nagios_plugins.md) | This collector runs Nagios-compatible checks, tracks the execution state of each configured job, measures how long each check takes to run, and automatically charts any performance data the check prints. |

578 +| [Nagios Plugins](https://github.com/netdata/netdata/blob/master/src/go/plugin/scripts.d/collector/nagios/integrations/nagios_plugins.md) | This collector runs [Nagios-compatible plugins](https://www.nagios-plugins.org/) and custom scripts. |

579 | [Ping](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/ping/integrations/ping.md) | This module measures round-trip time and packet loss by sending ping messages to network hosts. |

580 | [Site 24x7](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/prometheus/integrations/site_24x7.md) | Monitor Site24x7 website and infrastructure monitoring metrics for efficient performance tracking and management. |

581 | [TCP/UDP Endpoints](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/portcheck/integrations/tcp-udp_endpoints.md) | Collector for monitoring service availability and response time. |

src/go/plugin/scripts.d/collector/nagios/integrations/nagios_plugins.md

+242 -85

@@ -21,10 +21,130 @@ Module: nagios

22 ## Overview

24 -This collector runs Nagios-compatible checks, tracks the execution state of each configured job, measures how long each check takes to run, and automatically charts any performance data the check prints. For non-counter perfdata, Netdata also derives a plugin-scoped threshold-state chart for visualization and a static `nagios.job.perfdata.threshold_state` duplicate for alerting. When the check does not provide warning or critical ranges, the threshold state is `no_threshold`.

24 +This collector runs [Nagios-compatible plugins](https://www.nagios-plugins.org/) and custom scripts. It provides:

26 +- **Check state monitoring** — tracks whether each check returns OK, WARNING, CRITICAL, or UNKNOWN

27 +- **Execution metrics** — measures run duration, CPU time, and memory usage of each check

28 +- **Automatic performance data charts** — any [Nagios performance data](https://nagios-plugins.org/doc/guidelines.html) in the check output is parsed and charted automatically

29 +- **Threshold-based alerting** — when performance data includes warning/critical thresholds, Netdata derives threshold state and creates built-in alerts

27 -Netdata runs the configured Nagios-compatible command for each job, reads the process exit code to determine the check state, and parses the command output into a summary line, optional long output, and optional performance data. Any performance data found after the `|` separator is converted into charts automatically. The main perfdata value becomes a chart, and non-counter metrics also get derived threshold-state output in two forms: a plugin-scoped chart for visualization and a static `nagios.job.perfdata.threshold_state` chart labeled by `perfdata_value` for stock alerting. If the check does not provide warning or critical ranges, that threshold state is `no_threshold`. You can use packaged Nagios plugins or your own scripts, and you can control how often checks run, how retries behave, and when checks are allowed to run by using the job configuration.

31 +

32 +Netdata executes each configured command on a schedule, reads the process exit code to determine the check state, and parses the standard output for a status message and optional [performance data](https://nagios-plugins.org/doc/guidelines.html). Any performance data is automatically converted into charts.

33 +

34 +:::tip

35 +

36 +You can use packaged [Nagios plugins](https://www.nagios-plugins.org/) or write your own scripts — any executable that follows the Nagios plugin output format will work.

37 +

38 +:::

39 +

40 +<details open><summary><strong>Nagios Plugin Output Format</strong></summary>

41 +

42 +A Nagios-compatible plugin communicates through two channels: the **process exit code** and **standard output**. For the full specification, see the [Nagios Plugin Development Guidelines](https://nagios-plugins.org/doc/guidelines.html).

43 +

44 +#### Exit Codes

45 +

46 +The exit code is the **only** thing that determines the check state — the output text is for display purposes only.

47 +

48 +| Exit Code | State | Meaning |

49 +|:---------:|:------|:--------|

50 +| 0 | **OK** | Check passed |

51 +| 1 | **WARNING** | Above warning threshold or degraded |

52 +| 2 | **CRITICAL** | Above critical threshold or service down |

53 +| 3 | **UNKNOWN** | Invalid arguments or internal error |

54 +

55 +#### Standard Output

56 +

57 +The output follows this structure:

58 +

59 +```text

60 +STATUS TEXT | perfdata1=val;warn;crit;min;max perfdata2=val

61 +LONG OUTPUT LINE 1

62 +LONG OUTPUT LINE 2 | more_perfdata=val

63 +```

64 +

65 +| Part | Description |

66 +|:-----|:------------|

67 +| **Status text** | Text before the pipe on the first line. Shown as the job's status message. |

68 +| **Performance data** | Text after the pipe on any line. Parsed into charts automatically. |

69 +| **Long output** | Lines 2+ before the pipe. Additional detail text. |

70 +

71 +> **Note:** The pipe separator is optional. Without it, the entire first line is the status text and no performance data charts are created.

72 +

73 +#### Performance Data Format

74 +

75 +Each performance data metric uses this format:

76 +

77 +```text

78 +'label'=value[UOM];[warn];[crit];[min];[max]

79 +```

80 +

81 +| Field | Required | Description |

82 +|:------|:--------:|:------------|

83 +| `label` | Yes | Metric name. Quote with single quotes if it contains spaces. |

84 +| `value` | Yes | Numeric value. |

85 +| `UOM` | No | Unit of measurement (see table below). |

86 +| `warn` | No | Warning threshold range. |

87 +| `crit` | No | Critical threshold range. |

88 +| `min` | No | Minimum possible value. |

89 +| `max` | No | Maximum possible value. |

90 +

91 +Separate multiple metrics with spaces.

92 +

93 +**Supported Units of Measurement (UOM):**

94 +

95 +| UOM | Meaning | How Netdata charts it |

96 +|:----|:--------|:----------------------|

97 +| *(none)* | Unitless number | Charted as-is |

98 +| `s` | Seconds (also `ms`, `us`, `ns`) | Normalized to seconds |

99 +| `%` | Percentage | Charted as percentage |

100 +| `B` | Bytes (also `KB`, `MB`, `GB`, `TB`) | Charted in bytes |

101 +| `b` | Bits (also `Kb`, `Mb`, `Gb`, `Tb`) | Charted in bits |

102 +| `c` | Continuous counter | Charted as incremental rate |

103 +

104 +#### Threshold Ranges

105 +

106 +Thresholds use the format `[@]start:end`, where a bare number like `10` is shorthand for `0:10` and `~` represents negative infinity (no lower bound). An alert triggers when the value falls **outside** the range (or **inside** with the `@` prefix):

107 +

108 +| Range | Alert when... |

109 +|:------|:--------------|

110 +| `10` | value < 0 or value > 10 |

111 +| `10:` | value < 10 |

112 +| `~:10` | value > 10 |

113 +| `10:20` | value < 10 or value > 20 |

114 +| `@10:20` | 10 ≤ value ≤ 20 |

115 +

116 +When `warn` and `crit` ranges are provided on non-counter metrics, Netdata automatically derives a threshold state (ok / warning / critical) and creates charts with built-in alerts.

117 +

118 +**Common threshold patterns:**

119 +

120 +| I want to alert when... | `warn` | `crit` |

121 +|:------------------------|:-------|:-------|

122 +| Value exceeds a limit (e.g., response time > 2s) | `~:2` | `~:5` |

123 +| Value drops below a floor (e.g., free space < 10%) | `10:` | `5:` |

124 +| Value is outside a band (e.g., temperature 20–80) | `20:80` | `10:90` |

125 +

126 +#### Example

127 +

128 +A minimal Nagios-compatible script:

129 +

130 +```bash

131 +#!/bin/sh

132 +echo "OK - 85% free memory | free_pct=85%;20:;10:;0;100 used_kb=2380912KB;;;0;16380000"

133 +exit 0

134 +```

135 +

136 +This produces:

137 +- **Check state**: OK (exit code 0)

138 +- **Status text**: `OK - 85% free memory`

139 +- **Charts**: `free_pct` (percentage with warning/critical thresholds) and `used_kb` (bytes)

140 +

141 +</details>

142 +

143 +:::info

144 +

145 +**Retry behavior:** When a check returns a non-OK state, Netdata does not alert immediately. The check enters a **soft state** and retries at the `retry_interval` rate. Only after `max_check_attempts` consecutive failures does it become a **hard state** and trigger alerts. If the check recovers during retries, it returns to OK without alerting. The `retry` dimension on state charts indicates a soft state is in progress.

146 +

147 +:::

148

149

150 This collector is supported on all platforms.

@@ -57,7 +177,7 @@ Metrics grouped by *scope*.

177

178 The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

179

60 -Each configured job exposes execution-state and execution-resource charts. Netdata also emits a plugin-scoped copy of the job state named `nagios.perfdata.<plugin>.job.execution_state` so the state appears under each configured check section in the UI. If a check prints Nagios performance data, Netdata also creates additional value charts automatically from the values emitted by that check. For non-counter perfdata, Netdata creates both a plugin-scoped threshold-state chart for visualization and a static `nagios.job.perfdata.threshold_state` duplicate labeled by `perfdata_value` for alerting. Counter perfdata currently exposes only the value chart.

180 +Each configured job produces execution state and resource usage charts. When a check emits Nagios performance data, additional charts are created automatically for each metric. Non-counter perfdata with warning/critical thresholds also get threshold state charts for alerting.

181

182

183 ### Per job

@@ -69,14 +189,14 @@ Labels:

189 | Label | Description |

190 |:-----------|:----------------|

191 | nagios_job | Job name as defined in the configuration. |

72 -| perfdata_value | Normalized perfdata identity in the form `<class>_<metric_key>`, used by the static threshold-state duplicate. |

192 +| perfdata_value | Identifies which performance data metric a threshold state belongs to. Format is `<unit_class>_<label>`, where `<unit_class>` is derived from the UOM (`time`, `bytes`, `bits`, `percent`, or `generic`) and `<label>` is the sanitized metric label from the check output. For example, `repl_lag=5s` produces `time_repl_lag`. |

193

194 Metrics:

195

196 | Metric | Dimensions | Unit |

197 |:------|:----------|:----|

198 | nagios.job.execution_state | ok, warning, critical, unknown, timeout, paused, retry | state |

79 -| nagios.job.perfdata.threshold_state | no_threshold, ok, warning, critical, retry | state |

199 +| nagios.job.perfdata_threshold_state | no_threshold, ok, warning, critical, retry | state |

200 | nagios.job.execution_duration | duration | seconds |

201 | nagios.job.execution_cpu_total | total | seconds |

202 | nagios.job.execution_max_rss | rss | bytes |

@@ -118,77 +238,15 @@ dnf install nagios-plugins-all

238 Make sure the configured command path exists and is executable by the `netdata` user.

239

240

121 -#### Write Nagios-compatible checks

122 -

123 -A compatible check uses two things:

124 -

125 -- the **exit code** to tell Netdata whether the result is OK, WARNING, CRITICAL, or UNKNOWN

126 -- the **command output** to show a human-readable message and optional performance data

127 -

128 -Use these exit codes:

129 -

130 -- `0` = OK

131 -- `1` = WARNING

132 -- `2` = CRITICAL

133 -- `3` = UNKNOWN

134 -

135 -The first output line should follow this pattern:

136 -

137 -```text

138 -<summary text> | <perfdata>

139 -```

140 -

141 -The `|` separator is optional:

142 -

143 -- everything before `|` is the human-readable summary

144 -- everything after `|` is performance data used for automatic charts

145 -

146 -The summary should be short and useful because it is the main status text shown for the job. If the script prints multiple lines, Netdata uses the first line as the summary and keeps the remaining lines as long output.

147 -

148 -Each performance-data item follows this format:

149 -

150 -```text

151 -'label'=value[UOM];warn;crit;min;max

152 -```

153 -

154 -Only `label` and `value` are required. The threshold and range fields are optional. Separate multiple metrics with spaces.

155 -

156 -Common units include:

157 -

158 -- `%` for percentages

159 -- `s`, `ms`, `us` for durations

160 -- `B`, `KB`, `MB`, `GB` for sizes

161 -- `c` for counters

241 +#### Prepare custom check scripts

242

163 -Example output:

243 +If you are writing your own check scripts instead of using packaged Nagios plugins:

244

165 -```text

166 -OK - 85.5% free memory | free_pct=85.5%;20;10;0;100 free_kb=13999088KB;;;0;16380000

167 -```

168 -

169 -In that example:

170 -

171 -- the exit code decides the state

172 -- `OK - 85.5% free memory` is the summary line

173 -- `free_pct=85.5%;20;10;0;100` creates a percentage metric

174 -- `free_kb=13999088KB;;;0;16380000` creates a size metric

175 -- the warning and critical ranges on non-counter metrics are also used to derive threshold-state output for both visualization and alerting

176 -

177 -Good rules to follow:

178 -

179 -- return the correct exit code

180 -- keep the first line short and readable

181 -- put performance data after `|`

182 -- separate multiple metrics with spaces

183 -- quote labels if they contain spaces

184 -

185 -Minimal example:

186 -

187 -```bash

188 -#!/bin/sh

189 -echo "CPU OK - 20% used | cpu=20%;80;90"

190 -exit 0

191 -```

245 +- Place scripts anywhere accessible to the `netdata` user (e.g., `/usr/local/lib/netdata/checks/`)

246 +- Make scripts executable: `chmod +x /path/to/script.sh`

247 +- Test as the `netdata` user to verify permissions and environment: `sudo -u netdata /path/to/script.sh`

248 +- Verify the exit code: `echo $?` (must be 0, 1, 2, or 3)

249 +- Verify the output matches the Nagios plugin output format described in the Overview above

250

251

252

@@ -205,23 +263,53 @@ Add jobs under `jobs:`. Each job runs one Nagios-compatible check command.

263

265 |:------|:-----|:------------|:--------|:---------:|

208 -| **Collection** | update_every | How often Netdata evaluates the job schedule, in seconds. | 10 | no |

209 -| | autodetection_retry | How often Netdata retries failed auto-detection jobs, in seconds. Set `0` to keep auto-detection disabled. | 0 | no |

210 -| **Target** | plugin | Absolute path to the Nagios-compatible executable to run. This can be a packaged Nagios plugin or your own executable. If you need a script interpreter, point `plugin` to that interpreter and pass the script path in `args`. The command should return exit code `0`, `1`, `2`, or `3` and may print performance data after `/`. | | yes |

266 +| **Collection** | update_every | How often the collector's internal scheduler ticks, in seconds. Controls chart granularity. In most cases you only need to set `check_interval`. | 10 | no |

267 +| **Target** | plugin | Absolute path to the Nagios-compatible executable to run. This can be a packaged Nagios plugin or your own executable. If you need a script interpreter, point `plugin` to that interpreter and pass the script path in `args`. The command should return exit code `0`, `1`, `2`, or `3` and may print performance data after <code>|</code>. | | yes |

268 | | args | Arguments passed to the command. | | no |

212 -| | arg_values | Values exposed to `$ARG1$` through `$ARG32$` for macro expansion. | | no |

269 +| | arg_values | Values exposed to `$ARG1$` through `$ARG32$` for macro expansion. The first value maps to `$ARG1$`, the second to `$ARG2$`, and so on. | | no |

270 | | working_directory | Working directory used when running the command. | | no |

271 | **Scheduling** | timeout | Maximum time allowed for one command run. If the check exceeds this limit, the job state becomes `timeout`. | 5s | no |

272 | | check_interval | Interval between regular checks. | 5m | no |

273 | | retry_interval | Interval between retries while a check remains in a non-OK soft state. | 1m | no |

274 | | max_check_attempts | Number of attempts before a non-OK result becomes a hard state. | 3 | no |

218 -| | check_period | Name of the time period that controls when the job is allowed to run. Outside this period, the check does not execute and the public job state becomes `paused`. | 24x7 | no |

219 -| | time_periods | Custom named time periods defined inside the same job. | | no |

221 -| | custom_vars | Custom service variables exposed to the check as Nagios-style macros. | | no |

275 +| | check_period | Name of the [time period](https://github.com/netdata/netdata/blob/master/src/go/plugin/scripts.d/pkg/timeperiod/README.md) that controls when the job is allowed to run. The built-in `24x7` period (always allowed) is the default. Outside the active period, the check does not execute and the job state becomes `paused`. | 24x7 | no |

276 +| | time_periods | Custom named [time periods](https://github.com/netdata/netdata/blob/master/src/go/plugin/scripts.d/pkg/timeperiod/README.md) defined inside the same job. Supports `weekly`, `nth_weekday`, and `date` rule types. | | no |

277 +| **Environment** | [environment](#option-environment-environment) | Extra environment variables added on top of the collector's limited execution baseline. The check does not inherit the full Netdata process environment. | | no |

278 +| | [custom_vars](#option-environment-custom-vars) | Custom service variables exposed to the check as Nagios-style macros. | | no |

281

282 +<a id="option-environment-environment"></a>

283 +##### environment

284 +

285 +A key-value map of environment variables injected into the check's process. Use this when your script depends on variables that are not part of the collector's default environment.

286 +

287 +```yaml

288 +jobs:

289 + - name: oracle_check

290 + plugin: /usr/local/bin/check_oracle.sh

291 + environment:

292 + ORACLE_HOME: /opt/oracle/product/19c

293 + LD_LIBRARY_PATH: /opt/oracle/product/19c/lib

294 +```

295 +

296 +

297 +<a id="option-environment-custom-vars"></a>

298 +##### custom_vars

299 +

300 +A key-value map of custom service variables. Each entry is exposed as a `NAGIOS__SERVICE<UPPERCASE_KEY>` environment variable and can be referenced in `args` using the Nagios macro syntax `$_SERVICE<KEY>$`.

301 +

302 +```yaml

303 +jobs:

304 + - name: check_db

305 + plugin: /usr/lib/nagios/plugins/check_pgsql

306 + args: ["-H", "$_SERVICEDBHOST$", "-d", "$_SERVICEDBNAME$"]

307 + custom_vars:

308 + DBHOST: db.example.com

309 + DBNAME: production

310 +```

311 +

312 +

313

314 </details>

315

@@ -261,9 +349,68 @@ jobs:

349 ```

350 </details>

351

264 -###### Custom script

352 +###### End-to-end custom script

353 +

354 +Write a custom check script, then configure Netdata to run it.

355 +

356 +**1. Create the script** (e.g., `/usr/local/lib/netdata/checks/check_api.sh`):

357 +

358 +```bash

359 +#!/bin/sh

360 +# Check HTTP endpoint health

361 +URL="http://localhost:8080/health"

362 +

363 +response=$(curl -s -o /dev/null -w "%{http_code} %{time_total}" --max-time 5 "$URL" 2>/dev/null)

364 +curl_exit=$?

365 +

366 +if [ "$curl_exit" -ne 0 ]; then

367 + echo "UNKNOWN - Could not connect to $URL (curl exit code $curl_exit)"

368 + exit 3

369 +fi

370 +

371 +http_code=$(echo "$response" | cut -d' ' -f1)

372 +response_time=$(echo "$response" | cut -d' ' -f2)

373 +

374 +if [ "$http_code" -ge 500 ]; then

375 + echo "CRITICAL - $URL returned HTTP $http_code | response_time=${response_time}s;2;5;0;"

376 + exit 2

377 +elif [ "$http_code" -ne 200 ]; then

378 + echo "WARNING - $URL returned HTTP $http_code | response_time=${response_time}s;2;5;0;"

379 + exit 1

380 +fi

381 +

382 +echo "OK - $URL returned HTTP $http_code | response_time=${response_time}s;2;5;0;"

383 +exit 0

384 +```

385 +

386 +**2. Make it executable and test it:**

387 +

388 +```bash

389 +chmod +x /usr/local/lib/netdata/checks/check_api.sh

390 +sudo -u netdata /usr/local/lib/netdata/checks/check_api.sh

391 +echo "Exit code: $?"

392 +```

393 +

394 +**3. Add the configuration below, then restart Netdata** (`sudo systemctl restart netdata`). After restarting, look for `nagios.job.execution_state` and related charts in the Netdata dashboard.

395 +

396 +

397 +<details open><summary>Config</summary>

398 +

399 +```yaml

400 +jobs:

401 + - name: api_health

402 + plugin: /usr/local/lib/netdata/checks/check_api.sh

403 + timeout: 10s

404 + check_interval: 1m

405 + retry_interval: 30s

406 + max_check_attempts: 3

407 +

408 +```

409 +</details>

410 +

411 +###### Custom script (minimal)

412

266 -Run your own Nagios-compatible shell script.

413 +Run your own Nagios-compatible shell script with minimal configuration.

414

415 <details open><summary>Config</summary>

416

@@ -359,7 +506,17 @@ Nagios checks run with a limited execution environment rather than inheriting th

506

507 ### Built-in alerts cover warning and critical states only

508

362 -This collector installs stock Netdata health alerts for the `warning` and `critical` states on `nagios.job.execution_state` and `nagios.job.perfdata_threshold_state`. Both stock alert families suppress soft retry states by checking that `retry` is not active. If you also want alerts for `unknown`, `timeout`, `paused`, or more specific perfdata behavior, build your own rules on top of these contexts. The `job.perfdata.threshold_state` chart uses the `perfdata_value` label to identify which perfdata metric each threshold state belongs to.

509 +This collector installs stock Netdata health alerts for the `warning` and `critical` states on `nagios.job.execution_state` and `nagios.job.perfdata_threshold_state`. Both stock alert families suppress soft retry states by checking that `retry` is not active. If you also want alerts for `unknown`, `timeout`, `paused`, or more specific perfdata behavior, build your own rules on top of these contexts. The `nagios.job.perfdata_threshold_state` chart uses the `perfdata_value` label to identify which perfdata metric each threshold state belongs to.

510 +

511 +

512 +### Configuration changes are not picked up

513 +

514 +After editing `scripts.d/nagios.conf`, restart the Netdata Agent for changes to take effect: `sudo systemctl restart netdata`.

515 +

516 +

517 +### Script stderr output is not visible

518 +

519 +Netdata captures the check's standard output for status and performance data parsing. Standard error (stderr) is logged by the collector but not used for state or charts. If your script writes errors to stderr, check the Netdata error log for details.

520

521

522 ### Windows checks need an executable entry point