Skip to content

samber/cc-skills-golang / skills/golang-troubleshooting

golang-troubleshooting

Verified

Troubleshoot Golang programs systematically - find and fix the root cause. Use when encountering bugs, crashes, deadlocks, races, or unexpected behavior in Go code. Covers debugging methodology, common Go pitfalls, test-driven debugging, pprof setup and capture, Delve, race detection, GODEBUG tracing, and production debugging. Start here for any 'something is wrong' situation. Not for interpreting profiles or benchmarking (→ See `samber/cc-skills-golang@golang-benchmark` skill), applying optimization patterns (→ See `samber/cc-skills-golang@golang-performance` skill), or designing new code (→ See `samber/cc-skills-golang@golang-safety` skill for defensive coding, `samber/cc-skills-golang@golang-concurrency` skill for concurrency design).

references/performance-debug.md

View on GitHub
# Performance Troubleshooting

## CPU Profiling

Use pprof CPU profile to capture a 30s sample (see [pprof.md](./pprof.md) for commands), then inspect with `top`, `web`, or `list funcName`.

**Common CPU hogs:**

1. JSON marshal/unmarshal in hot path — preallocate buffers, use faster libraries
2. Reflection in critical path
3. Unnecessary allocations — use sync.Pool
4. O(n^2) hidden in nested loops
5. Too many syscalls — batch operations

## Memory Profiling

Use pprof heap profile (see [pprof.md](./pprof.md)). Compare heap snapshots over time with `go tool pprof -base heap1.prof heap2.prof` to find growth. Use escape analysis (see [diagnostic-tools.md](./diagnostic-tools.md)) to find unexpected heap allocations in hot paths.

**Common memory leaks:**

1. Unbounded cache without eviction
2. Growing slices in loops (forgetting to reset)
3. Global maps never cleared
4. String concatenation in loops (use `strings.Builder`)
5. Large structs passed by value

## Lock Contention

**Symptoms:** CPU high but throughput low, latency increases with load, multiple cores don't help.

**Enable profiling in code:**

```go
runtime.SetMutexProfileFraction(1)
runtime.SetBlockProfileRate(1)
```

Then use pprof mutex and block profiles (see [pprof.md](./pprof.md)).

**Solutions:**

1. Reduce critical section — hold lock for minimal time
2. Sharding — multiple locks for different data
3. `sync.Map` — for read-heavy workloads
4. `atomic` — for simple counters
5. `RWMutex` — when reads >> writes
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall