werkator/docs/prs/2026-10-03-PR#100-swap-warning.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

On Hostsharing swap is not welcome: swapped pages still go into the backup and into the DRBD mirror. That is to change some day, but it holds today. The System page and the home page showed the swap in use in the same colour, whether it was 10 MB or 3 GB. Nobody noticed when a host started to swap.

Non-Goals

• The health verdict stays as it is: swap in use is no waiting, and RFC 0004 judges waiting only.
• The sizing stays as it is, for the same reason.

The Scenarios

Feature: Swap above a threshold shows amber

Scenario#100.01: The swap readings turn amber above the threshold

So that a host that starts to swap stands out without changing the verdict.

• Given a snapshot with more swap in use than metrics.swapWarningGib
• When the System page and the home page render it
• Then the swap tile of each is marked warn, and no other tile is
• And the health verdict stays healthy
• And at or below the threshold the tiles stay calm

Verified by

• UiViewsUnitTest — Scenario#100.01

Scenario#100.02: The snapshot carries the threshold

So that werkator.js judges the polled swap exactly like the server, and a changed instance file takes effect without a restart.

• Given a collector reading the threshold from the instance file
• When it samples, the threshold changes, and it samples again
• Then each snapshot carries the threshold of its sample

Verified by

• SystemMetricsCollectorUnitTest — Scenario#100.02

Scenario#100.03: 0.5 GiB by default, off with null

So that the Hostsharing hosts need no change, and another host can raise or drop the warning.

• Given an instance file without, with 2.0, and with null for metrics.swapWarningGib
• When the configuration is loaded
• Then the threshold is 0.5, 2.0, and none

Verified by

• ConfigLoaderUnitTest — Scenario#100.03

The Solution

• MetricsConfig.swapWarningGib, instance-level like the whole metrics section, defaults to 0.5. It is a plain threshold in GiB, not a share of the swap size: what costs is every swapped page.
• SystemMetricsCollector reads it with every sample and puts it into the snapshot, so GET /api/system carries it.
• UiFormats.swapLevel and its twin swapLevel in werkator.js say warn above it.
• TileView and HomeMetricView got a level; the templates add level-warn, and werkator.css colours the value amber.

Additional Changes

• docs/configuration.md and the init template describe the key.
• Version 1.31.0 with its release note.