refactor(cpu-usage): non-blocking behaviour (interval=None + manual deltas via SQLite DB) so we get both accuracy and faster runtime

Author: markuslf

CHANGELOG.md

@@ -64,6 +64,7 @@ Icinga Director:
 
 Monitoring Plugins:
 
+* cpu-usage: non-blocking behaviour (interval=None + manual deltas via SQLite DB) so we get both accuracy and faster runtime
 * gitlab-health: increase timeout from 3 to 8 secs
 * gitlab-liveness: increase timeout from 3 to 8 secs
 * gitlab-readiness: increase timeout from 3 to 8 secs

check-plugins/cpu-usage/README.md

@@ -2,13 +2,18 @@
 
 ## Overview
 
-Returns a bunch of numbers representing the current system-wide CPU utilization as a percentage. Outputs the cpu times having \> 0% in the first line, sorted by value. In addition, the top 5 processes which consumed the most CPU time are listed. Warns only if any of `user`, `system`, `iowait` or overall `cpu-usage` is above a certain threshold within the last n checks (default: 5).
+Reports CPU utilization percentages for all available time categories (user, system, idle, nice, iowait, irq, softirq, steal, guest, guest_nice) plus the overall cpu-usage (100 − idle − nice).
+
+Thresholds (WARN/CRIT) are checked against user, system, iowait, and cpu-usage. An alert is raised only if the threshold is exceeded for COUNT consecutive runs, suppressing short spikes and focusing on sustained load.
+
+Perfdata is emitted for every field to enable full graphing. Extended stats (context switches, interrupts, etc.) are included if supported on this platform. With `--top`, the most CPU-intensive processes are also listed for quick diagnosis.
+
+This check is cross-platform and works on Linux, Windows, and all psutil-supported systems.
 
 Hints and Recommendations:
 
 * We check system-wide CPU stats, not per-CPU.
 * `--count=5` (the default) while checking every minute means that the check reports a warning if any of `user`, `system`, `iowait` or overall `cpu-usage` was above a threshold in the last 5 minutes.
-* Check needs at least 250ms to run.
 
 
 ## Fact Sheet
@@ -30,9 +35,16 @@ Hints and Recommendations:
 usage: cpu-usage [-h] [-V] [--always-ok] [--count COUNT] [-c CRIT] [--top TOP]
                  [-w WARN]
 
-Mainly provides utilization percentages for each specific CPU time. Takes a
-time period into account: the cpu usage within a certain amount of time has to
-be equal or above given thresholds before a warning is raised.
+Reports CPU utilization percentages for all available time categories (user,
+system, idle, nice, iowait, irq, softirq, steal, guest, guest_nice) plus the
+overall cpu-usage (100 − idle − nice). Thresholds (WARN/CRIT) are checked
+against user, system, iowait, and cpu-usage. An alert is raised only if the
+threshold is exceeded for COUNT consecutive runs, suppressing short spikes and
+focusing on sustained load. Perfdata is emitted for every field to enable full
+graphing. Extended stats (context switches, interrupts, etc.) are included if
+supported on this platform. With `--top`, the most CPU-intensive processes are
+also listed for quick diagnosis. This check is cross-platform and works on
+Linux, Windows, and all psutil-supported systems.
 
 options:
   -h, --help           show this help message and exit
@@ -42,8 +54,9 @@ options:
                        thresholds before alerting. Default: 5
   -c, --critical CRIT  Set the critical threshold CPU Usage Percentage.
                        Default: 90
-  --top TOP            List x "Top processes using the most cpu time".
-                       Default: 5
+  --top TOP            List x "Top processes using the most cpu time". Use
+                       `--top=0` to disable this feature. Default: 5 on Linux,
+                       0 on Windows
   -w, --warning WARN   Set the warning threshold CPU Usage Percentage.
                        Default: 80
 ```
@@ -52,7 +65,7 @@ options:
 ## Usage Examples
 
 ```bash
-./cpu-usage --count=15 --warning=50 --critical=70
+./cpu-usage --count=15 --warning=50 --critical=70 --top=3
 ```
 
 Output:
@@ -62,7 +75,7 @@ Output:
 guest: 0.0%, iowait: 0.0%, guest_nice: 0.0%, steal: 0.0%, nice: 0.0%
 interrupts: 582.9M, soft_interrupts: 343.6M, ctx_switches: 1.1G
 
-Top3 processes using the most cpu time:
+Top 3 processes using the most cpu time:
 1. Xorg: 2h 13m
 2. gnome-shell: 2h 1m
 3. firefox: 1h 24m