Go Performance Testing
Optimize only after establishing a representative, repeatable measurement and a
specific hypothesis.
Core Workflow
- Define the user-visible metric and representative workload.
- Stabilize correctness before measuring performance.
- Write focused benchmarks with realistic inputs and controlled setup.
- Collect repeated baseline samples in comparable conditions.
- Use allocations, profiles, and traces to form a causal hypothesis.
- Make one bounded change.
- Compare repeated before/after samples statistically.
- Recheck correctness and the end-to-end workload.
Read Next
| Task |
Load |
| Benchmark a function or package |
guidelines.md, workflows/benchmark-code.md |
| Investigate a regression |
workflows/investigate-performance.md |
| Evaluate profile-guided optimization |
workflows/evaluate-pgo.md |
| Choose benchmark and profile controls |
references/performance-testing/rules.md |
| Interpret metrics and profiles |
references/performance-testing/knowledge.md |
| Review benchmark patterns |
references/performance-testing/examples.md |
Guardrails
- Do not optimize from one benchmark line or an unrepresentative microbenchmark.
- Do not compare runs made under materially different environments.
- Do not treat coverage or race detection as performance evidence.
- Name the profile sample type and distinguish flat from cumulative cost.
- Prefer
B.Loop only when the pinned Go version supports it.
- Keep production profile endpoints protected and operationally controlled.
- Do not encode cache-line size, escape output, or inliner budgets as portable facts.
- Do not use
sync.Pool as a cache or resource owner.
Source Notes
Guidance is transformed and paraphrased from Inanc Gumus, Go by Example:
Programmer's Guide to Idiomatic and Testable Programs (Manning, 2025),
especially Chapter 3. Examples are original.
Diagnostics, locality, allocation, GC, and container guidance also incorporates
transformed material from Teiva Harsanyi, 100 Go Mistakes and How to Avoid
Them (Manning, 2022), Chapter 12.
Book: https://www.manning.com/books/go-by-example
Verify current behavior against https://pkg.go.dev/testing,
https://go.dev/doc/diagnostics, and https://go.dev/doc/pgo.
1---2name: go-performance-testing3description: Design, run, compare, and interpret Go performance evidence using benchmarks, B.Loop, benchstat, pprof, traces, escape analysis, cache locality, false sharing, sync.Pool, GC limits, container CPU behavior, and PGO. Use when investigating Go latency, throughput, CPU, memory, allocations, contention, runtime behavior, performance regressions, or optimization claims.4license: MIT5compatibility: Codex, Claude Code, and other Agent Skills-compatible clients.6metadata:7 version: "0.2.0"8 displayName: Go Performance Testing9 category: Go10 tags: go,golang,benchmarks,profiling,pprof,performance11---1213# Go Performance Testing1415Optimize only after establishing a representative, repeatable measurement and a16specific hypothesis.1718## Core Workflow19201. Define the user-visible metric and representative workload.212. Stabilize correctness before measuring performance.223. Write focused benchmarks with realistic inputs and controlled setup.234. Collect repeated baseline samples in comparable conditions.245. Use allocations, profiles, and traces to form a causal hypothesis.256. Make one bounded change.267. Compare repeated before/after samples statistically.278. Recheck correctness and the end-to-end workload.2829## Read Next3031| Task | Load |32|---|---|33| Benchmark a function or package | `guidelines.md`, `workflows/benchmark-code.md` |34| Investigate a regression | `workflows/investigate-performance.md` |35| Evaluate profile-guided optimization | `workflows/evaluate-pgo.md` |36| Choose benchmark and profile controls | `references/performance-testing/rules.md` |37| Interpret metrics and profiles | `references/performance-testing/knowledge.md` |38| Review benchmark patterns | `references/performance-testing/examples.md` |3940## Guardrails4142- Do not optimize from one benchmark line or an unrepresentative microbenchmark.43- Do not compare runs made under materially different environments.44- Do not treat coverage or race detection as performance evidence.45- Name the profile sample type and distinguish flat from cumulative cost.46- Prefer `B.Loop` only when the pinned Go version supports it.47- Keep production profile endpoints protected and operationally controlled.48- Do not encode cache-line size, escape output, or inliner budgets as portable facts.49- Do not use `sync.Pool` as a cache or resource owner.5051## Source Notes5253Guidance is transformed and paraphrased from Inanc Gumus, *Go by Example:54Programmer's Guide to Idiomatic and Testable Programs* (Manning, 2025),55especially Chapter 3. Examples are original.5657Diagnostics, locality, allocation, GC, and container guidance also incorporates58transformed material from Teiva Harsanyi, *100 Go Mistakes and How to Avoid59Them* (Manning, 2022), Chapter 12.6061Book: https://www.manning.com/books/go-by-example6263Verify current behavior against https://pkg.go.dev/testing,64https://go.dev/doc/diagnostics, and https://go.dev/doc/pgo.
LVTD-LLC