werkator/docs/prs/2026-10-03-PR#102-swap-traffic.md

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.

The Problem

Since PR#100 the swap tile turns amber when more swap is in use than metrics.swapWarningGib. On Hostsharing, though, swap that stays costs little: backup and DRBD cost mainly where blocks change. What costs is swap traffic: every page swapped in or out is a changed block that DRBD sends to the remote mirror, which takes bandwidth. Werkator did not measure that traffic, so a host that kept swapping below 0.5 GiB looked calm.

Non-Goals

• The occupancy rule stays: either rule is enough for amber.
• No sizing rule yet: the traffic is recorded first, as RFC 0004 asks, and judged once its numbers are understood.
• The health verdict is unchanged.

The Scenarios

Feature: Swap traffic colours the swap readings

Scenario#102.01: Swap traffic is measured over five minutes

So that a single short burst does not count like a host that keeps swapping.

• Given the pswpin and pswpout counters of /proc/vmstat
• When samples are taken a minute apart, ten minutes apart, and after a counter went backwards
• Then the traffic is null for a single sample, the pages moved per second in MiB/s, zero once the burst left the window, and null again after a reboot
• And every snapshot carries both thresholds

Verified by

• SystemMetricsCollectorUnitTest — Scenario#102.01

Scenario#102.02: Traffic turns the readings amber and red, occupancy only amber

So that only what costs the mirror can raise the alarm.

• Given snapshots with traffic below, at the warning, and at the critical threshold, and with a lot of swap in use but no traffic
• When the swap level is judged
• Then it is calm, amber, and red, and amber for the occupancy alone
• And the System page's swap tile reads in use · moving 1.25 MiB/s, and the home rail's tooltip says the same

Verified by

• UiViewsUnitTest — Scenario#102.02

Scenario#102.03: 0.1 and 1.0 MiB/s by default, off with null

So that the defaults are cautious, and a host can set its own.

• Given an instance file without and with the two keys
• When the configuration is loaded
• Then the thresholds are 0.1 and 1.0, or what the file says, and null turns one off

Verified by

• ConfigLoaderUnitTest — Scenario#102.03

The Solution

• SystemMetricsCollector reads pswpin and pswpout with every sample and keeps five minutes of counts in memory; the traffic is the pages moved since the oldest of them, at 4 KiB a page. It goes into the snapshot and into the history as the series swapTraffic.
• MetricsConfig has swapTrafficWarningMibPerSecond (0.1) and swapTrafficCriticalMibPerSecond (1.0), instance-level like the rest of metrics, and the snapshot carries them for werkator.js.
• UiFormats.swapLevel takes the whole snapshot now: critical traffic is red, warning traffic, the occupancy above swapWarningGib or half the swap is amber; werkator.js decides the same way.
• The defaults are set low on purpose: 0.1 MiB/s for a day is about 8 GB through the mirror.

Additional Changes

• docs/configuration.md and the init template describe the two keys.
• Version 1.33.0 with its release note.

Follow-up PRs

• A RAM sizing rule on swap traffic, once a few weeks of the swapTraffic series show what its numbers mean.