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