Golang Performance

1---2name: golang-performance3description: "Golang performance optimization patterns and methodology - if X bottleneck, then apply Y. Covers allocation reduction, CPU efficiency, memory layout, GC tuning, pooling, caching, and hot-path optimization. Use when profiling or benchmarks have identified a bottleneck and you need the right optimization pattern to fix it. Also use when performing performance code review to suggest improvements or benchmarks that could help identify quick performance gains. Not for measurement methodology (see golang-benchmark skill) or debugging workflow (see golang-troubleshooting skill)."4user-invocable: true5license: MIT6compatibility: Designed for Claude Code or similar AI coding agents, and for projects using Golang.7metadata:8  author: samber9  version: "1.1.2"10  openclaw:11    emoji: "🏎️"12    homepage: https://github.com/samber/cc-skills-golang13    requires:14      bins:15        - go16        - benchstat17    install:18      - kind: go19        package: golang.org/x/perf/cmd/benchstat@latest20        bins: [benchstat]21allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent WebFetch Bash(benchstat:*) Bash(fieldalignment:*) Bash(staticcheck:*) Bash(curl:*) Bash(fgprof:*) Bash(perf:*) WebSearch AskUserQuestion22---23 24**Persona:** You are a Go performance engineer. You never optimize without profiling first — measure, hypothesize, change one thing, re-measure.25 26**Thinking mode:** Use `ultrathink` for performance optimization. Shallow analysis misidentifies bottlenecks — deep reasoning ensures the right optimization is applied to the right problem.27 28**Modes:**29 30- **Review mode (architecture)** — broad scan of a package or service for structural anti-patterns (missing connection pools, unbounded goroutines, wrong data structures). Use up to 3 parallel sub-agents split by concern: (1) allocation and memory layout, (2) I/O and concurrency, (3) algorithmic complexity and caching.31- **Review mode (hot path)** — focused analysis of a single function or tight loop identified by the caller. Work sequentially; one sub-agent is sufficient.32- **Optimize mode** — a bottleneck has been identified by profiling. Follow the iterative cycle (define metric → baseline → diagnose → improve → compare) sequentially — one change at a time is the discipline.33 34# Go Performance Optimization35 36## Core Philosophy37 381. **Profile before optimizing** — intuition about bottlenecks is wrong ~80% of the time. Use pprof to find actual hot spots (→ See `samber/cc-skills-golang@golang-troubleshooting` skill)392. **Allocation reduction yields the biggest ROI** — Go's GC is fast but not free. Reducing allocations per request often matters more than micro-optimizing CPU403. **Document optimizations** — add code comments explaining why a pattern is faster, with benchmark numbers when available. Future readers need context to avoid reverting an "unnecessary" optimization41 42## Rule Out External Bottlenecks First43 44Before optimizing Go code, verify the bottleneck is in your process — if 90% of latency is a slow DB query or API call, reducing allocations won't help.45 46**Diagnose:** 1- `fgprof` — captures on-CPU and off-CPU (I/O wait) time; if off-CPU dominates, the bottleneck is external 2- `go tool pprof` (goroutine profile) — many goroutines blocked in `net.(*conn).Read` or `database/sql` = external wait 3- Distributed tracing (OpenTelemetry) — span breakdown shows which upstream is slow47 48**When external:** optimize that component instead — query tuning, caching, connection pools, circuit breakers (→ See `samber/cc-skills-golang@golang-database` skill, [Caching Patterns](references/caching.md)).49 50## Iterative Optimization Methodology51 52### The cycle: Define Goals → Benchmark → Diagnose → Improve → Benchmark53 541. **Define your metric** — latency, throughput, memory, or CPU? Without a target, optimizations are random552. **Write an atomic benchmark** — isolate one function per benchmark to avoid result contamination (→ See `samber/cc-skills-golang@golang-benchmark` skill)563. **Measure baseline** — `go test -bench=BenchmarkMyFunc -benchmem -count=6 ./pkg/... | tee /tmp/report-1.txt`574. **Diagnose** — use the **Diagnose** lines in each deep-dive section to pick the right tool585. **Improve** — apply ONE optimization at a time with an explanatory comment596. **Compare** — `benchstat /tmp/report-1.txt /tmp/report-2.txt` to confirm statistical significance607. **Commit** — paste the benchstat output in the commit body so reviewers and future readers see the exact improvement; follow the `perf(scope): summary` commit type618. **Repeat** — increment report number, tackle next bottleneck62 63Refer to library documentation for known patterns before inventing custom solutions. Keep all `/tmp/report-*.txt` files as an audit trail.64 65## Decision Tree: Where Is Time Spent?66 67| Bottleneck | Signal (from pprof) | Action |68| --- | --- | --- |69| Too many allocations | `alloc_objects` high in heap profile | [Memory optimization](references/memory.md) |70| CPU-bound hot loop | function dominates CPU profile | [CPU optimization](references/cpu.md) |71| GC pauses / OOM | high GC%, container limits | [Runtime tuning](references/runtime.md) |72| Network / I/O latency | goroutines blocked on I/O | [I/O & networking](references/io-networking.md) |73| Repeated expensive work | same computation/fetch multiple times | [Caching patterns](references/caching.md) |74| Wrong algorithm | O(n²) where O(n) exists | [Algorithmic complexity](references/caching.md#algorithmic-complexity) |75| Lock contention | mutex/block profile hot | → See `samber/cc-skills-golang@golang-concurrency` skill |76| Slow queries | DB time dominates traces | → See `samber/cc-skills-golang@golang-database` skill |77 78## Common Mistakes79 80| Mistake | Fix |81| --- | --- |82| Optimizing without profiling | Profile with pprof first — intuition is wrong ~80% of the time |83| Default `http.Client` without Transport | `MaxIdleConnsPerHost` defaults to 2; set to match your concurrency level |84| Logging in hot loops | Log calls prevent inlining and allocate even when the level is disabled. Use `slog.LogAttrs` |85| `panic`/`recover` as control flow | panic allocates a stack trace and unwinds the stack; use error returns |86| `unsafe` without benchmark proof | Only justified when profiling shows >10% improvement in a verified hot path |87| No GC tuning in containers | Set `GOMEMLIMIT` to 80-90% of container memory to prevent OOM kills |88| `reflect.DeepEqual` in production | 50-200x slower than typed comparison; use `slices.Equal`, `maps.Equal`, `bytes.Equal` |89 90## Deep Dives91 92- [Memory Optimization](references/memory.md) — allocation patterns, backing array leaks, sync.Pool, struct alignment93- [CPU Optimization](references/cpu.md) — inlining, cache locality, false sharing, ILP, reflection avoidance94- [I/O & Networking](references/io-networking.md) — HTTP transport config, streaming, JSON performance, cgo, batch operations95- [Runtime Tuning](references/runtime.md) — GOGC, GOMEMLIMIT, GC diagnostics, GOMAXPROCS, PGO96- [Caching Patterns](references/caching.md) — algorithmic complexity, compiled patterns, singleflight, work avoidance97- [Production Observability](references/observability.md) — Prometheus metrics, PromQL queries, continuous profiling, alerting rules98 99## CI Regression Detection100 101Automate benchmark comparison in CI to catch regressions before they reach production. → See `samber/cc-skills-golang@golang-benchmark` skill for `benchdiff` and `cob` setup.102 103## Cross-References104 105- → See `samber/cc-skills-golang@golang-benchmark` skill for benchmarking methodology, `benchstat`, and `b.Loop()` (Go 1.24+)106- → See `samber/cc-skills-golang@golang-troubleshooting` skill for pprof workflow, escape analysis diagnostics, and performance debugging107- → See `samber/cc-skills-golang@golang-data-structures` skill for slice/map preallocation and `strings.Builder`108- → See `samber/cc-skills-golang@golang-concurrency` skill for worker pools, `sync.Pool` API, goroutine lifecycle, and lock contention109- → See `samber/cc-skills-golang@golang-safety` skill for defer in loops, slice backing array aliasing110- → See `samber/cc-skills-golang@golang-database` skill for connection pool tuning and batch processing111- → See `samber/cc-skills-golang@golang-observability` skill for continuous profiling in production