# Golang Performance

> Go performance workflow: benchmark and profile (pprof/trace), identify hotspots, reduce allocations/GC and contention, and verify improvements with repeatable measurement. Use only after you have evidence the Go code is the bottleneck.

- Skill: `aeondave/golang-performance` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add aeondave/golang-performance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aeondave/golang-performance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: MIT
- Author: AeonDave (https://skillmd.com/u/aeondave)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aeondave/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 + `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