@cryptotaxi247 / netdata-1 / commits / 86fda42af

Regenerate integrations docs (#22006)

Co-authored-by: ilyam8 <22274335+ilyam8@users.noreply.github.com>

Netdata bot committed Mar 23, 2026 at 07:12 UTC 86fda42af07cc70526f42769dcb1c695e206cc94
3 files changed +372
src/collectors/COLLECTORS.md
+1
@@ -575,6 +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. |
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/README.md new
+1
@@ -0,0 +1 @@
1 +integrations/nagios_plugins.md
\ No newline at end of file
src/go/plugin/scripts.d/collector/nagios/integrations/nagios_plugins.md new
+370
@@ -0,0 +1,370 @@
1 +<!--startmeta
2 +custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/go/plugin/scripts.d/collector/nagios/README.md"
3 +meta_yaml: "https://github.com/netdata/netdata/edit/master/src/go/plugin/scripts.d/collector/nagios/metadata.yaml"
4 +sidebar_label: "Nagios Plugins"
5 +learn_status: "Published"
6 +learn_rel_path: "Collecting Metrics/Synthetic Testing"
7 +keywords: ['nagios', 'plugins', 'checks', 'scripts', 'monitoring']
8 +message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
9 +endmeta-->
10 +
11 +# Nagios Plugins
12 +
13 +
14 +<img src="https://netdata.cloud/img/nagios.png" width="150"/>
15 +
16 +
17 +Plugin: scripts.d.plugin
18 +Module: nagios
19 +
20 +<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
21 +
22 +## Overview
23 +
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`.
25 +
26 +
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.
28 +
29 +
30 +This collector is supported on all platforms.
31 +
32 +This collector supports collecting metrics from multiple instances of this integration, including remote instances.
33 +
34 +No additional permissions are required by the collector itself. If a check needs access to protected files, sockets, or system commands, provide that access to the check command or helper it uses.
35 +
36 +
37 +### Default Behavior
38 +
39 +#### Auto-Detection
40 +
41 +No automatic detection is performed. Add one or more jobs explicitly and point each job to the script or executable you want Netdata to run.
42 +
43 +
44 +#### Limits
45 +
46 +Each job runs one configured command. Additional charts are created only when the check emits Nagios performance data.
47 +
48 +
49 +#### Performance Impact
50 +
51 +Each job starts an external command. The impact depends mostly on how often the job runs and how expensive the check command itself is.
52 +
53 +
54 +## Metrics
55 +
56 +Metrics grouped by *scope*.
57 +
58 +The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
59 +
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.
61 +
62 +
63 +### Per job
64 +
65 +These metrics refer to each configured check job.
66 +
67 +Labels:
68 +
69 +| Label | Description |
70 +|:-----------|:----------------|
71 +| 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. |
73 +
74 +Metrics:
75 +
76 +| Metric | Dimensions | Unit |
77 +|:------|:----------|:----|
78 +| 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 |
80 +| nagios.job.execution_duration | duration | seconds |
81 +| nagios.job.execution_cpu_total | total | seconds |
82 +| nagios.job.execution_max_rss | rss | bytes |
83 +
84 +
85 +
86 +## Alerts
87 +
88 +
89 +The following alerts are available:
90 +
91 +| Alert name | On metric | Description |
92 +|:------------|:----------|:------------|
93 +| [ nagios_job_execution_state_warn ](https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf) | nagios.job.execution_state | Nagios job ${label:nagios_job} is in WARNING state |
94 +| [ nagios_job_execution_state_crit ](https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf) | nagios.job.execution_state | Nagios job ${label:nagios_job} is in CRITICAL state |
95 +| [ nagios_job_perfdata_threshold_state_warn ](https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf) | nagios.job.perfdata_threshold_state | Nagios job ${label:nagios_job} perfdata ${label:perfdata_value} is in WARNING threshold state |
96 +| [ nagios_job_perfdata_threshold_state_crit ](https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf) | nagios.job.perfdata_threshold_state | Nagios job ${label:nagios_job} perfdata ${label:perfdata_value} is in CRITICAL threshold state |
97 +
98 +
99 +## Setup
100 +
101 +
102 +### Prerequisites
103 +
104 +#### Install check commands
105 +
106 +Install the Nagios plugins or other Nagios-compatible scripts that you want Netdata to run.
107 +
108 +Most Linux distributions provide Nagios plugin packages:
109 +
110 +```bash
111 +# Debian/Ubuntu
112 +apt install nagios-plugins
113 +
114 +# RHEL/CentOS/Fedora
115 +dnf install nagios-plugins-all
116 +```
117 +
118 +Make sure the configured command path exists and is executable by the `netdata` user.
119 +
120 +
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
162 +
163 +Example output:
164 +
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 +```
192 +
193 +
194 +
195 +### Configuration
196 +
197 +#### Options
198 +
199 +Add jobs under `jobs:`. Each job runs one Nagios-compatible check command.
200 +
201 +
202 +<details open><summary>Config options</summary>
203 +
204 +
205 +
206 +| Group | Option | Description | Default | Required |
207 +|:------|:-----|:------------|:--------|:---------:|
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 |
211 +| | args | Arguments passed to the command. | | no |
212 +| | arg_values | Values exposed to `$ARG1$` through `$ARG32$` for macro expansion. | | no |
213 +| | working_directory | Working directory used when running the command. | | no |
214 +| **Scheduling** | timeout | Maximum time allowed for one command run. If the check exceeds this limit, the job state becomes `timeout`. | 5s | no |
215 +| | check_interval | Interval between regular checks. | 5m | no |
216 +| | retry_interval | Interval between retries while a check remains in a non-OK soft state. | 1m | no |
217 +| | 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 |
220 +| **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 |
221 +| | custom_vars | Custom service variables exposed to the check as Nagios-style macros. | | no |
222 +| **Virtual Node** | vnode | Associate the job with a virtual node so the check can use host-specific labels and macros. | | no |
223 +| **Misc** | notes | Optional notes for the job definition. | | no |
224 +
225 +
226 +</details>
227 +
228 +
229 +
230 +#### via File
231 +
232 +The configuration file name for this integration is `scripts.d/nagios.conf`.
233 +
234 +
235 +You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the
236 +Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).
237 +
238 +```bash
239 +cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
240 +sudo ./edit-config scripts.d/nagios.conf
241 +```
242 +
243 +##### Examples
244 +
245 +###### Basic check
246 +
247 +Run a Nagios check command on a fixed interval.
248 +
249 +<details open><summary>Config</summary>
250 +
251 +```yaml
252 +jobs:
253 + - name: ping_localhost
254 + plugin: /usr/lib/nagios/plugins/check_ping
255 + args: ["-H", "127.0.0.1", "-w", "100.0,20%", "-c", "200.0,40%"]
256 + timeout: 5s
257 + check_interval: 1m
258 + retry_interval: 30s
259 + max_check_attempts: 3
260 +
261 +```
262 +</details>
263 +
264 +###### Custom script
265 +
266 +Run your own Nagios-compatible shell script.
267 +
268 +<details open><summary>Config</summary>
269 +
270 +```yaml
271 +jobs:
272 + - name: custom_memory_check
273 + plugin: /opt/netdata/check_memory.sh
274 + timeout: 5s
275 + check_interval: 1m
276 +
277 +```
278 +</details>
279 +
280 +###### Check with a job-local schedule
281 +
282 +Run a check only during selected hours by defining time periods inside the job.
283 +
284 +<details open><summary>Config</summary>
285 +
286 +```yaml
287 +jobs:
288 + - name: business_hours_http
289 + plugin: /usr/lib/nagios/plugins/check_http
290 + args: ["-H", "example.com"]
291 + check_period: business_hours
292 + time_periods:
293 + - name: business_hours
294 + alias: Business hours
295 + rules:
296 + - type: weekly
297 + days: [monday, tuesday, wednesday, thursday, friday]
298 + ranges: ["09:00-18:00"]
299 +
300 +```
301 +</details>
302 +
303 +###### Check with virtual node macros
304 +
305 +Run a check against a virtual node and fill command arguments from Nagios-style macros.
306 +
307 +<details open><summary>Config</summary>
308 +
309 +```yaml
310 +jobs:
311 + - name: check_ssh
312 + plugin: /usr/lib/nagios/plugins/check_ssh
313 + args: ["-H", "$HOSTADDRESS$", "-p", "$ARG1$"]
314 + arg_values: ["22"]
315 + vnode: remote-server
316 + check_interval: 5m
317 +
318 +```
319 +</details>
320 +
321 +
322 +
323 +## Troubleshooting
324 +
325 +### The command cannot be executed
326 +
327 +Confirm that the path in `plugin` exists, is executable, and can be accessed by the `netdata` user. If the check depends on external files or helpers, verify those paths and permissions too.
328 +
329 +
330 +### No performance-data charts appear
331 +
332 +Performance-data charts are created only when the check prints Nagios performance data after the `|` separator. If the command returns only a status line without performance data, Netdata will still show the job state but no extra charts.
333 +
334 +
335 +### Some performance-data values are ignored
336 +
337 +Check that each metric uses the Nagios performance-data format `label=value[UOM];warn;crit;min;max` and that multiple metrics are separated by spaces. If a label contains spaces, quote it. Netdata charts the main value for every perfdata metric, and for non-counter metrics it derives threshold state from `warn` and `crit`; it does not create separate charts for raw `min`, `max`, or raw threshold bounds.
338 +
339 +
340 +### The job state does not match the output text
341 +
342 +The visible text does not decide the state. Netdata uses the process exit code instead: `0` for OK, `1` for WARNING, `2` for CRITICAL, and `3` for UNKNOWN. If the check exceeds the configured `timeout`, Netdata reports `timeout` even if the script never had a chance to print its own final state. If the current time is outside `check_period`, Netdata reports `paused` until the check is allowed to run again.
343 +
344 +
345 +### Only the first output line appears as the main status
346 +
347 +This is expected. Netdata uses the first line as the summary shown for the job. Additional lines are kept as long output, and any `|` sections found on later lines are also parsed for performance data.
348 +
349 +
350 +### Macros are not expanded as expected
351 +
352 +Check that positional values are provided in `arg_values`, custom service variables are defined in `custom_vars`, and any virtual-node labels needed for host macros are present on the selected `vnode`.
353 +
354 +
355 +### The script works in a shell but fails under Netdata
356 +
357 +Nagios checks run with a limited execution environment rather than inheriting the full Netdata process environment. If the script depends on extra variables, set them explicitly in `environment` instead of relying on ambient shell state.
358 +
359 +
360 +### Built-in alerts cover warning and critical states only
361 +
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.
363 +
364 +
365 +### Windows checks need an executable entry point
366 +
367 +The collector runs the command named in `plugin` directly. On Windows, point `plugin` to an executable or to an interpreter such as `powershell.exe` and pass the script path in `args`.
368 +
369 +
370 +