Documentation
¶
Overview ¶
Command allocsgate is the allocs/op regression gate for the perf CI workflow (docs/adr/0019-perf-tracking.md Phase 3; .github/workflows/perf.yml). It compares two `go test -bench -benchmem` outputs and FAILS (exit 1) iff some benchmark's allocs/op rose beyond an epsilon (delta >= 1 whole alloc AND > 2 %).
WHY A GO PROGRAM, NOT A SHELL/PYTHON HEREDOC: the gate decision is load-bearing, so it must be TESTED (main_test.go) and live in ONE place — the two workflow jobs (perf-pr, perf-main) both call it, rather than duplicating a parser. It is also FAIL-CLOSED: an empty/corrupt bench file does NOT silently pass the hard gate.
allocs/op is the gated signal because it is deterministic — it does not move with CPU load, so no statistical significance test is needed (that is benchstat's job, and benchstat is the LOCAL human A/B tool, not the CI gate decision).
It imports ONLY the standard library — no engine/..., no internal/..., same leaf posture as perf/kpi.
Usage:
allocsgate <old.txt> <new.txt>
<old.txt> is the previous-main baseline; it may be ABSENT (first run, before any baseline has been published) — in that case the gate skips green. <new.txt> is this run's bench output and must be non-empty.
Source Files