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](../../src/test/kotlin/de/hoennig/werkator/metrics/SystemMetricsCollectorUnitTest.kt) — 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](../../src/test/kotlin/de/hoennig/werkator/server/UiViewsUnitTest.kt) — 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](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderUnitTest.kt) — 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.