Skip to content

Commit 689b62c

Browse files
committed
docs(docker-stats,podman-stats): clarify when per-container perfdata is useful
Add an Important Notes bullet to both READMEs: per-container CPU and memory perfdata work for long-lived containers with stable names (traefik, named systemd-managed services). For ever-changing workloads (GitLab runner jobs, CI builders) the labels churn between check runs and are useless for trending - the aggregate perfdata is the right signal there. Trim the now-redundant Perfdata section intro to point back to the Important Notes. Re-sort the Important Notes bullets alphabetically while in the area.
1 parent 64aa4f7 commit 689b62c

2 files changed

Lines changed: 7 additions & 5 deletions

File tree

check-plugins/docker-stats/README.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,9 @@ Reports CPU and memory usage for all running Docker containers. CPU usage is nor
77

88
**Important Notes:**
99

10-
* Plugin execution may take up to 10 seconds due to `docker stats --no-stream`
1110
* Container names are shortened after the replica number by default (e.g. `traefik_traefik.2`). Use `--full-name` to show the full container name
11+
* Per-container CPU and memory perfdata are most useful for long-lived containers with stable names (e.g. `traefik_traefik.2`, named systemd-managed services). For ever-changing workloads (e.g. GitLab runner jobs, CI builders), the per-container labels churn between check runs and are useless for trending. The aggregate perfdata is the right signal there
12+
* Plugin execution may take up to 10 seconds due to `docker stats --no-stream`
1213

1314
**Data Collection:**
1415

@@ -108,7 +109,7 @@ myconti_ds_1 ! 0.0 ! 11.42
108109

109110
## Perfdata / Metrics
110111

111-
The plugin emits one CPU and one memory metric per container so individual workloads can be plotted long-term. Because container names appear and disappear as workloads come and go, the time-series backend (Graphite, InfluxDB, ...) will keep stale entries until they are pruned.
112+
One CPU and one memory metric is emitted per running container, plus the aggregate metrics below. See the Important Notes for when per-container metrics are and aren't useful.
112113

113114
| Name | Type | Description |
114115
|----|----|----|

check-plugins/podman-stats/README.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,11 @@ Reports CPU and memory usage for all running Podman containers. CPU usage is nor
77

88
**Important Notes:**
99

10-
* Podman runs rootless by default. Without `sudo`, the check only sees containers of the executing user. To monitor containers across all users, run the check via `sudo` (the Icinga Director basket and sudoers file are pre-configured for this).
10+
* Memory usage is relative to the container's memory limit if one is set, otherwise relative to the total host memory.
11+
* Per-container CPU and memory perfdata are most useful for long-lived containers with stable names (e.g. `traefik_traefik.2`, named systemd-managed services). For ever-changing workloads (e.g. GitLab runner jobs, CI builders), the per-container labels churn between check runs and are useless for trending. The aggregate perfdata is the right signal there.
1112
* Plugin execution may take up to 10 seconds.
13+
* Podman runs rootless by default. Without `sudo`, the check only sees containers of the executing user. To monitor containers across all users, run the check via `sudo` (the Icinga Director basket and sudoers file are pre-configured for this).
1214
* Since `podman stats` only returns byte-level data in a human-readable format (e.g. *221.2kB*), calculating network I/O and block I/O is imprecise. Therefore, these values are only reported as aggregate perfdata.
13-
* Memory usage is relative to the container's memory limit if one is set, otherwise relative to the total host memory.
1415

1516
**Data Collection:**
1617

@@ -109,7 +110,7 @@ myconti_ds_1 ! 0.0 ! 11.42
109110

110111
## Perfdata / Metrics
111112

112-
The plugin emits one CPU and one memory metric per container so individual workloads can be plotted long-term. Because container names appear and disappear as workloads come and go, the time-series backend (Graphite, InfluxDB, ...) will keep stale entries until they are pruned.
113+
One CPU and one memory metric is emitted per running container, plus the aggregate metrics below. See the Important Notes for when per-container metrics are and aren't useful.
113114

114115
| Name | Type | Description |
115116
|----|----|----|

0 commit comments

Comments
 (0)