Documentation
¶
Overview ¶
Package perfgate checks count metrics against the ratchet ceilings in automation/perf/ratchet.toml.
A gate test measures a count that does not depend on machine speed (allocations, bytes, GC cycles, goroutines, descriptors, child processes, crossings, file sizes) and calls Check with the metric's ID. Check fails when the count exceeds the ceiling or the ID has no ceiling, and logs one `perfgate: <id>=<value> ceiling=<ceiling>` line that `make perf-scoreboard-measure` collects. Ceilings only move down: automation/perf/scoreboard.py --ratchet-base rejects a raised ceiling. Only test code imports this package.
Index ¶
- Constants
- func Ceiling(t testing.TB, id string) float64
- func Check(t testing.TB, id string, got float64)
- func CheckAnonymous(t testing.TB, id string, memory Memory)
- func Descendant(pid int, comm string) int
- func DisableTransparentHugePages() error
- func Exponent(smallN, largeN int, small, large float64) float64
- func Report(t testing.TB, id string, got float64)
- type Memory
- type Ratchet
- type Scaling
- type Work
Constants ¶
const RatchetPath = "automation/perf/ratchet.toml"
RatchetPath is the ceiling file, relative to the module root.
Variables ¶
This section is empty.
Functions ¶
func Ceiling ¶
Ceiling returns the ceiling of id, failing t when the ratchet file cannot be read or has no entry for id.
func CheckAnonymous ¶
CheckAnonymous gates memory.Anon against the ceiling of id. A process whose anonymous memory is huge-page backed is not measured at all: the figure would depend on the host's THP policy and on page alignment, so the gate fails and names the cause instead of comparing it.
func Descendant ¶
Descendant returns the first process named comm below pid, searching children breadth-first through /proc/<pid>/task/*/children, or 0.
func DisableTransparentHugePages ¶
func DisableTransparentHugePages() error
DisableTransparentHugePages stops the kernel from backing this process's anonymous memory with transparent huge pages. The setting is inherited across fork and kept across exec, so every process the caller starts afterwards (a measured pig, the tmux server a pane's pig runs under) is measured with 4 KiB pages.
The memory ceilings were derived on a host whose THP policy is "madvise", where the Go runtime's heap is not huge-page backed. GitHub's Ubuntu runners use "always": a heap that touches 3 MB of one 8 MB arena then shows as two or three whole 2 MiB pages (AnonHugePages 4 to 6 MB), so the same binary measured an anonymous 5.65 to 7.77 MB there instead of 3.9 to 4.0 MB. Which of those it showed depended on where the heap's pages fell relative to the 2 MiB boundaries, not on what the code allocated, so the figure could neither gate code changes nor be compared across hosts.
func Exponent ¶
Exponent is the power law that takes cost small at size smallN to cost large at size largeN: cost grows as size^Exponent. A constant cost has exponent 0, a linear cost 1, a quadratic cost 2. A cost of zero counts as one allocation or byte, so a path that starts at zero and grows reports a finite exponent.
Types ¶
type Memory ¶
type Memory struct {
Rss, Pss, Anon, AnonHuge float64
}
Memory is a process's resident memory in bytes, as /proc/<pid>/smaps_rollup accounts it.
Rss and Pss count every resident page the process maps, so they include the pages of the binary and of shared libraries the kernel has in its page cache: how many of those are mapped at a given moment depends on readahead and on what else touched the file, not on the process. Anon is the pages that belong to the process alone (its heap, stacks and written data), which does not, as long as the kernel backs them with 4 KiB pages: AnonHuge is the part of Anon held in transparent huge pages, which are 2 MiB granular (see DisableTransparentHugePages).
type Scaling ¶
Scaling is the heap allocation of one operation at three sizes a decade apart: N, 10N and 100N.
func CheckScaling ¶
func CheckScaling(t testing.TB, id string, sizes [3]int, prepare func(size int) (operation func())) Scaling
CheckScaling measures the operation at sizes N, 10N and 100N, logs every cost, and fails t when the cost grows faster than the ceilings of id+".allocs_exponent" and id+".bytes_exponent" allow. The ceiling names the exponent it pins: 0 for a cost independent of the size, 1 for a cost proportional to it, 2 for a quadratic one. A ceiling is the measured exponent rounded up with a margin for the constant part of the cost; it only moves down. It returns the measurement.
func MeasureScaling ¶
MeasureScaling measures the operation at each size. prepare builds the state of one size (not measured) and returns the one operation whose allocation is counted; the operation must leave that state as it found it, because it runs once to warm caches and then scalingRepeats times under Measure. Like Measure, the count is process-wide, so the caller keeps other goroutines idle.
type Work ¶
type Work struct {
Allocs, Bytes float64
}
Work is the heap allocation of one measured call.
func CheckLinear ¶
CheckLinear fails t when the marginal bytes per unit at 2n exceed growth times the marginal at n: the per-unit cost must not grow with the length of what came before. It returns the marginal at n.
func Marginal ¶
Marginal returns the allocation that each unit adds between run(n) and run(2n), divided by n. A cost that is constant per unit gives the same marginal at every n; a cost that grows with the units already processed (a copy of everything so far per unit) doubles when n doubles.
func Measure ¶
func Measure(fn func()) Work
Measure runs fn once to warm caches, then once more under GOMAXPROCS=1 and returns the heap allocations of the second call: the steady-state cost of fn, with every sync.Pool it draws on already filled. Like testing.AllocsPerRun, the count is process-wide, so the caller keeps other goroutines idle.
No collection starts during either call. A collection empties every sync.Pool: the first moves a pool's items to its victim cache and the next drops them. A collection that starts between the warm call's Put and the counted call's Get therefore makes the counted call allocate the buffer again (net/http's 32 KiB copy buffer, a 64 KiB body read buffer, a bufio buffer): tens of kilobytes that belong to when the collector happened to run and not to fn, which a ceiling set at the steady-state cost cannot absorb. The collector runs on heap growth, and it runs at any time under load or a small GOGC, so Measure collects once to start from the live heap and then turns the collector off until the counted call returns. The heap grows by what the two calls allocate and is collected afterwards.