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.

Important Notes:

  • How full swap is says little about whether the host suffers from it. A host can sit at 80 percent swap usage for weeks without anyone noticing, while another one thrashes at 20 percent. The traffic to and from swap is what hurts, and the memory-paging check reports it as a rate.

Data Collection:

  • Uses psutil.swap_memory() to retrieve swap statistics (total, used, free, percent)
  • On Linux, 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 Cross-platform
Compiled for Windows Yes
3rd Party Python modules psutil

Help

usage: swap-usage [-h] [-V] [--always-ok] [-c CRIT] [--no-perfdata]
                  [--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
  --no-perfdata         Suppress the performance data section from the output.
                        The status message and the exit code are unaffected,
                        so alerting keeps working while trending data is
                        dropped.
  --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

Documentation:
https://linuxfabrik.github.io/monitoring-plugins/check-plugins/swap-usage/

Usage Examples

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

Output:

77.7% - total: 2.0GiB, used: 1.6GiB, free: 456.1MiB

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
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.

Unable to read the paging file usage

Unable to read the paging file usage from the performance counters.

Windows reads the paging file usage from a performance counter, and lets administrators, interactive sessions, NetworkService and members of the local group "Performance Monitor Users" read those. Where the Icinga 2 agent runs as an account of its own instead of NetworkService, add that account to "Performance Monitor Users" (Add-LocalGroupMember -SID S-1-5-32-558 -Member <account>, the SID names the group in every display language) and restart the agent.

If the account is allowed to read the counters, they are corrupt or disabled. Rebuild them, or make sure the registry key HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib has no value "Disable" (or set it to 0).

Credits, License