go-benchmark

Go Benchmark Methodology

Upstream: https://pkg.go.dev/testing#hdr-Benchmarks · https://pkg.go.dev/golang.org/x/perf/cmd/benchstat

Why Methodology Matters

A single run is a measurement, not an answer. Noise dwarfs changes under ~10%. Rules:

1. -count=6 minimum (statistical significance).
2. Compare with benchstat, not eyeball percentages.
3. Quiet machine — close heavy apps; plug in the laptop.
4. Always use -benchmem. Allocations are usually what changed.

testing.B Basics

func BenchmarkUserLookup(b *testing.B) {
    repo := newRepo(b)
    b.ReportAllocs() // force B/op + allocs/op output
    b.ResetTimer()   // drop setup cost
    for i := 0; i < b.N; i++ {
        _, err := repo.FindByID(context.Background(), 42)
        if err != nil { b.Fatal(err) }
    }
}

• b.N is adjusted by the framework until total runtime hits -benchtime (default 1s).
• Write the body so b.N iterations make sense.
• Don't swallow errors — use b.Fatal.

Timing Control

for i := 0; i < b.N; i++ {
    data := buildHeavyInput(i)
    b.StartTimer()
    _ = process(data)
    b.StopTimer()
}

Prefer b.ResetTimer before the loop; per-iteration Start/Stop adds overhead.

Throughput

payload := make([]byte, 4096)
b.SetBytes(int64(len(payload)))
b.ResetTimer()
for i := 0; i < b.N; i++ { _ = json.Unmarshal(payload, &out) }
// Output: ... 250 MB/s

Sub-Benchmarks

func BenchmarkSort(b *testing.B) {
    for _, n := range []int{100, 1_000, 10_000, 100_000} {
        b.Run(fmt.Sprintf("n=%d", n), func(b *testing.B) {
            data := randInts(n)
            b.ResetTimer()
            for i := 0; i < b.N; i++ {
                cp := slices.Clone(data)
                slices.Sort(cp)
            }
        })
    }
}

Target a slash pattern: go test -bench=BenchmarkSort/n=1000.

Running

go test -bench=. -benchmem -count=6 ./...
go test -bench=BenchmarkJSON -benchtime=3s -count=10
go test -bench=. -benchtime=1000x        # fixed iterations
go test -bench=. -cpu=1,2,4,8            # contention check
go test -bench=. ./pkg/cache/...