compswap

A small terminal dashboard for compressed swap on Linux. It covers both mechanisms the kernel offers:

• zswap: a compressed RAM cache placed in front of a regular swap device (disk partition or file). Pages are compressed and kept in RAM; only cold pages are written to disk.
• zram: a compressed block device living in RAM, used directly as a swap device (the default on Fedora, for example).

The kernel exposes a lot of numbers about them, scattered across /sys, /proc and debugfs. compswap detects which one is in use, gathers the numbers in one place, turns them into readable figures, and tells you whether your setup is working well.

To set them up, see the Arch Linux wiki pages on zswap and zram.

zram in action

zswap in action

What it shows

Sections are only displayed when they apply to your system.

• zswap: compressor, allocator, maximum pool size, shrinker state, amount of data stored, RAM actually used, compression ratio, RAM saved, and how full the pool is compared to its max_pool_percent limit.
• zram: devices and their algorithm and size, data stored, RAM used (with allocator overhead), real and raw compression ratios, RAM saved, same-filled and incompressible pages, fill level, memory limit and backing-device writeback when configured.
• Effective RAM: physical RAM plus what compression saves.
• Swap: swap usage split between zswap, zram and disk, plus every swap device with its type, priority and usage.
• Activity since boot: data written to / read from zswap, zram and disk, hit rate (share of swap-ins served from RAM), and zswap writeback to disk. Only the active mechanism is shown. When neither zswap nor zram is active, leftover counters from one used earlier since boot are shown instead, and marked as such.
• zswap details (debugfs): pool_limit_hit and non-zero reject_* counters (requires root).
• Diagnosis: a short list of hints about common problems, for example:
  • no compressed swap in use at all
  • zswap and zram both active (double compression)
  • zswap enabled with no swap device behind it
  • zswap pool full, with a suggested zswap.max_pool_percent value
  • zram almost full, with or without a disk swap to fall back on
  • zram with a lower priority than disk swap
  • zram write failures or mem_limit reached
  • low compression ratio or low hit rate
  • zswap shrinker disabled
  • vm.swappiness and vm.page-cluster values that suit zram poorly

Requirements

• Linux with zswap and/or zram support
• bash, awk, getconf (all standard)
• root access only for the zswap debugfs section (optional)

Installation

install -m 755 compswap.sh ~/.local/bin/compswap

Or just run the script from where it is.

Usage

compswap            # one-shot display
compswap -w [N]     # refresh every N seconds (default 2), Ctrl+C to quit
sudo compswap       # include detailed zswap debugfs counters
compswap -h         # help

Colors are disabled automatically when output is not a terminal, or when the NO_COLOR environment variable is set.

Data sources

Source	Used for
/sys/module/zswap/parameters	zswap configuration
/sys/kernel/debug/zswap	zswap pool limit hits and reject counters
/sys/block/zramN/	zram mm_stat, io_stat, stat, bd_stat, algorithm, size
/proc/meminfo	Zswap, Zswapped, RAM and swap size
/proc/vmstat	zswpin, zswpout, zswpwb, pswpin, pswpout
/proc/swaps	swap devices, usage and priorities
/proc/sys/vm	swappiness, page-cluster

zram reads and writes go through the block layer, so they are included in pswpin / pswpout; compswap subtracts them (using the zram device stat file) to get the real disk traffic.