Check swap-usage¶

Overview¶

Monitors swap space usage as a percentage of total swap. On Linux, optionally lists the top processes consuming the most swap to help identify the source of high usage.

Data Collection:

Uses psutil.swap_memory() to retrieve swap statistics (total, used, free, percent)
On Linux, also reports cumulative swap-in and swap-out bytes, and scans /proc for the top --top processes consuming the most swap
The top-processes feature is not available on Windows

Fact Sheet¶

Fact	Value
Check Plugin Download	https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/swap-usage
Nagios/Icinga Check Name	`check_swap_usage`
Check Interval Recommendation	Every minute
Can be called without parameters	Yes
Runs on	Linux
Compiled for Windows	Yes
3rd Party Python modules	`psutil`

Help¶

usage: swap-usage [-h] [-V] [--always-ok] [-c CRIT]
                  [--severity-no-swap {ok,warn,crit,unknown}] [--top TOP]
                  [-w WARN]

Monitors swap space usage as a percentage of total swap. Optionally lists the
top processes consuming the most swap to help identify the source of high
usage. Alerts when usage exceeds the configured thresholds. A host without any
swap is reported as OK; raise --severity-no-swap to warn or crit to flag a
missing swap partition where one is expected.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --always-ok           Always returns OK.
  -c, --critical CRIT   Threshold for swap usage, in percent. Default: 90
  --severity-no-swap {ok,warn,crit,unknown}
                        Severity for alerting if no swap is configured.
                        Default: ok
  --top TOP             Number of top processes consuming the most swap space
                        to list (not available on Windows). Default: 5
  -w, --warning WARN    Threshold for swap usage, in percent. Default: 70

Usage Examples¶

./swap-usage --warning 70 --critical 90 --top 3

Output:

77.7% - total: 2.0GiB, used: 1.6GiB, free: 456.1MiB
swapped in: 997.6MiB, swapped out: 2.6GiB (both cumulative)

Top 3 processes that use the most swap space:
1. php-fpm: 1.6GiB
2. icinga2: 7.7MiB
3. tuned: 3.9MiB

States¶

OK if swap usage is below the warning threshold.
WARN if swap usage is >= --warning (default: 70%).
CRIT if swap usage is >= --critical (default: 90%).
If no swap is configured at all (total swap is 0 bytes), reports No swap configured. and returns the state given by --severity-no-swap (default: OK, since a swapless host is a valid, fully-checked state). Set --severity-no-swap=warn or =crit to flag a missing swap partition on a host that is expected to have swap.
--always-ok suppresses all alerts and always returns OK.

Perfdata / Metrics¶

Name	Type	Description
free	Bytes	Free swap memory
sin	Bytes	Number of bytes the system has swapped in from disk (cumulative, Linux only)
sout	Bytes	Number of bytes the system has swapped out to disk (cumulative, Linux only)
total	Bytes	Total swap memory
usage_percent	Percentage	Swap usage calculated as (total - available) / total * 100
used	Bytes	Used swap memory

Troubleshooting¶

`Python module "psutil" is not installed.`¶

Install psutil: pip install psutil or dnf install python3-psutil.

Credits, License¶

Authors: Linuxfabrik GmbH, Zurich
License: The Unlicense, see LICENSE file.