miandmhoennig
4e0aa024ab
On Hostsharing swapped pages still go into the backup and the DRBD mirror. - New instance-level key `metrics.swapWarningGib`, default 0.5 GiB, `null` = off. - The swap tile on the System page and in the home rail turn amber above it (server-rendered and in werkator.js). - Display only: health verdict and sizing ignore swap occupancy (RFC 0004). PR-doc: `docs/prs/2026-10-03-PR#100-swap-warning.md` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: mhoennig <michael@hoennig.de> Reviewed-on: #100
71 lines
3.0 KiB
Markdown
71 lines
3.0 KiB
Markdown
> **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.
|