Skip to content

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]
                  [--test TEST] [-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. Returns a
configurable severity when no swap is configured at all, which helps detect a
swap partition that was inadvertently disabled.

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: unknown
  --top TOP             Number of top processes consuming the most swap space
                        to list (not available on Windows). Default: 5
  --test TEST           For unit tests. Needs "path-to-stdout-file,path-to-
                        stderr-file,expected-retc".
  -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: UNKNOWN). This helps detect a swap partition that was inadvertently disabled. Set --severity-no-swap=ok if running without swap is intentional on the host.
  • --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