210e66e3a4
A smaller bookable size that holds the peak, its headroom and the host's reserve is the whole proof of slack. vm4006 peaked at 7.04 of 12 GiB and read fits, while 10 GiB holds that peak at 73 %. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: mhoennig <michael@hoennig.de> Reviewed-on: #79
3.6 KiB
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
The Docker host vm4006 has 12 GiB of RAM booked and said fits on 2026-09-19.
Its RAM peak over eleven days was 7.04 GiB, the median 1.8 GiB, and no quarter hour ever stalled.
RAM is the expensive resource of that booking.
A downsize was considered only when the peak stayed below 40 % of the visible RAM (DOWNSIZE_RATIO).
7.04 of 11.69 GiB is 60 %, so the question was never asked.
The rule behind the gate would have answered it: 7.04 / 0.8 plus the 0.31 GiB the host keeps is 9.11, so 10 GiB holds the peak at 73 %.
The gate demanded a peak below 4.7 GiB before Werkator said anything.
The second condition of RFC 0004 D1 already carries the protection the gate was meant to give. A downsize is advised only when a smaller bookable size holds the peak with the target headroom. With RAM booked in whole GiB that condition is fine-grained enough to stand alone.
Non-Goals
- The RAM peak stays the window maximum, not a percentile as for disks (PR#78). A moment without memory is a build that stalls, which is the moment the machine exists for.
- The headroom stays 20 % (
TARGET_RATIO), the same line the RAM gauge turns amber at. Booking below the advice, 8 GiB on that host, remains the operator's experiment; stalled quarter hours would turn the advice totightorupgrade. - CPU and disk keep the 40 % gate. Their steps are coarse or their peaks short, and nothing asked for a change there.
The Scenarios
Feature: a RAM downsize is advised as soon as a smaller bookable size holds the peak
Scenario#79.01: A peak at 60 % still leaves a smaller size
- Given 12 GiB booked, 11.69 GiB visible, a peak of 7.04 GiB in eleven days and no stalled quarter hour
- When the capacity advice is computed with the Hostsharing steps
- Then RAM reads
downsizewith 10 GiB recommended - And the reason names the peak, the booked size and that nothing stalled
Verified by
- CapacitySizingTest — "the Docker host of 2026-09-19 …"
Scenario#79.02: No downsize without the headroom, and none while memory stalls
- Given the same host with a peak of 8.73 GiB
- When the advice is computed
- Then RAM reads
fits, because the 11 GiB below would put the peak above the target - And a host whose memory stalled reads
tightorupgrade, however low its peak
Verified by
- CapacitySizingTest — "a RAM peak the next smaller size would not hold …", "stalled memory is never downsized …"
The Solution
CapacitySizing.ram drops roomy from the downsize condition and keeps recommended <= smaller, guarded by smaller > 0.
DOWNSIZE_RATIO still decides whether a refused downsize is explained in the reason, since that text exists for a gauge that looks empty.
Two existing tests described a well-sized machine with 3.0 and 2.4 of 4.8 GiB. Under the new rule 4 GiB holds those peaks, so they now use 3.2 GiB, which needs the booked 5.
Open Questions
- A JVM without
-Xmxtakes a quarter of the visible RAM as its heap limit. Part of a measured peak may therefore shrink with the booking, which the advice cannot know.
Additional Changes
docs/deployment.mdand the architecture skill describe the RAM downsize rule.- Version 1.21.2 with its release note.