golang-performance

# Go Performance This skill is about **measurement-first optimization** in Go. ## When to activate Use this skill when you need to: - Confirm a performance regression (latency/throughput/CPU/memory) - Identify hot paths with pprof (CPU / heap / mutex / block) - Reduce allocations and GC pressure in a measured hotspot - Fix contention (mutex, scheduler, channel backpressure) - Validate improvements with benchmarks and repeatable runs If you need general idioms and patterns (not measurement), use `golang-patterns`. --- ## Rules of engagement - **Profile before optimizing.** A fast guess beats a slow change. - **Change one thing at a time.** Measure after each change. - **Keep a baseline.** Every claim should have “before vs after”. - **Don’t optimize the cold path.** Make the hot path boring. --- ## Outcome expectations - Performance claims are backed by reproducible before/after measurements. - Profile type selection matches the observed symptom. - Optimizations are incremental, attributable, and regression-resistant. --- ## Workflow 1. **Make it measurable** - Add a benchmark (or a reproducible load test) for the suspected hotspot. - Run multiple iterations; record mean + variance. 2. **Capture evidence** - CPU profile for time - Heap/allocs profile for memory - Mutex/block profiles for contention - Trace when the scheduler / GC behavior matters 3. **Analyze before changing code** - Identify top offenders (`top`, `top -cum`) - Inspect annotated source (`list`) - Confirm whether you are bound by CPU, allocations, syscalls, or contention 4. **Apply targeted fixes** - Allocation and GC: reduce allocations, reuse buffers, avoid retaining large backing arrays - Data layout: improve locality, avoid interface boxing in hot loops - Concurrency: reduce contention, bound goroutines, add backpressure 5. **Verify and document** - Re-run the benchmark/profile - Ensure correctness isn’t traded away - Record the change and its measured impact --- ## Symptom to first profile mapping - High CPU -> CPU profile - Memory growth -> heap profile (compare snapshots) - High allocation churn / GC pressure -> allocs profile - Latency spikes without CPU spike -> block profile - Lock contention suspicion -> mutex profile - Scheduler/pathological latency behavior -> runtime trace (flight recorder for rare events) - Growing goroutine count / suspected stuck workers -> `goroutineleak` profile, then the full goroutine profile - Shipped binary that is already profile-tuned and needs final runtime/build tuning -> `compiler-and-runtime-tuning.md` --- ## Safety note: exposing pprof `net/http/pprof` endpoints can leak sensitive runtime data. Prefer: - bind to `localhost` - protect with auth / firewall - enable only in dev / controlled environments --- ## Resources Load these references on demand: - `references/profiling.md` — pprof + trace (HTTP and `go test` capture) + `goroutineleak` + flight recorder - `references/benchmarks.md` — stable benchmarks, -benchmem, benchstat, hygiene - `references/allocations-gc.md` — allocation patterns, Green Tea GC, slice retention, sync.Pool - `references/contention.md` — mutex/block profiles, contention patterns, backpressure - `references/compiler-and-runtime-tuning.md` — load when code-level fixes have landed and you need PGO, GOGC/GOMEMLIMIT, GOMAXPROCS/cgroup, GC/cgo/thread knobs, or shipped-binary build flags