perfgate

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 11 Imported by: 0

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

View Source
const RatchetPath = "automation/perf/ratchet.toml"

RatchetPath is the ceiling file, relative to the module root.

Variables

This section is empty.

Functions

func Ceiling

func Ceiling(t testing.TB, id string) float64

Ceiling returns the ceiling of id, failing t when the ratchet file cannot be read or has no entry for id.

func Check

func Check(t testing.TB, id string, got float64)

Check fails t when got exceeds the ceiling of id.

func Descendant

func Descendant(pid int, comm string) int

Descendant returns the first process named comm below pid, searching children breadth-first through /proc/<pid>/task/*/children, or 0.

func Exponent

func Exponent(smallN, largeN int, small, large float64) float64

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.

func ProcessMemory

func ProcessMemory(t testing.TB, pid int) (rss, pss float64)

ProcessMemory returns the resident and proportional set sizes of process pid in bytes, from /proc/<pid>/smaps_rollup.

Types

type Ratchet

type Ratchet struct {
	Ceilings map[string]float64 `toml:"ceilings"`
}

Ratchet is the decoded ceiling file.

func Load

func Load(root string) (Ratchet, error)

Load decodes the ratchet file at root.

type Scaling

type Scaling struct {
	Sizes [3]int
	Cost  [3]Work
}

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

func MeasureScaling(sizes [3]int, prepare func(size int) (operation func())) Scaling

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.

func (Scaling) Exponents

func (s Scaling) Exponents() (allocs, bytes float64)

Exponents returns the largest exponent of the two decade steps (N to 10N, 10N to 100N) for allocations and bytes. The larger step is the one that shows a cost that is flat at small sizes and bends upward at large ones.

type Work

type Work struct {
	Allocs, Bytes float64
}

Work is the heap allocation of one measured call.

func CheckLinear

func CheckLinear(t testing.TB, id string, n int, growth float64, run func(units int)) Work

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

func Marginal(n int, run func(units int)) Work

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. Like testing.AllocsPerRun, the count is process-wide, so the caller keeps other goroutines idle.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL