Go Performance

Start with measurement, not rewriting.

Read the right reference

• Read references/measurement.md for benchmark setup, go test flags, pprof, trace, flight recording, runtime metrics, and PGO workflow.
• Read references/optimization.md when you are changing code after measurement or reviewing hot-path code.

Default workflow

1. Reproduce the problem and name the metric that matters: ns/op, B/op, allocs/op, throughput, tail latency, pause time, goroutine growth, or CPU saturation.
2. Add or repair a benchmark before changing code. On Go 1.24+ prefer b.Loop() for new or edited benchmarks unless the repo must support older Go.
3. Run the benchmark repeatedly and compare with benchstat; do not trust one run.
4. Collect one diagnostic at a time: CPU, heap/allocs, mutex, block, or trace. Do not mix profiles unless you must; diagnostics can distort each other.
5. Fix the dominant cost first: algorithmic complexity, redundant work, bad data layout, excess allocation, or contention.
6. Re-run the same benchmark and compare with benchstat.
7. Apply PGO only after the code path is correct and the profile is representative.
8. Validate the change under realistic service conditions with runtime metrics, net/http/pprof, or flight recording if the issue is production-only.