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 Descendant(pid int, comm string) int
- func Exponent(smallN, largeN int, small, large float64) float64
- func ProcessMemory(t testing.TB, pid int) (rss, pss float64)
- 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 Descendant ¶
Descendant returns the first process named comm below pid, searching children breadth-first through /proc/<pid>/task/*/children, or 0.
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 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.