samber/cc-skills-golang / skills/golang-troubleshooting
golang-troubleshooting
VerifiedTroubleshoot 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).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.0 KB |
| evals/evals.json | config | 45.0 KB |
| references/code-review-flags.md | markdown | 1.9 KB |
| references/common-go-bugs.md | markdown | 25.4 KB |
| references/compilation.md | markdown | 647 B |
| references/concurrency-debug.md | markdown | 3.0 KB |
| references/diagnostic-tools.md | markdown | 3.6 KB |
| references/methodology.md | markdown | 10.0 KB |
| references/performance-debug.md | markdown | 1.5 KB |
| references/pprof.md | markdown | 5.1 KB |
| references/production-debug.md | markdown | 3.7 KB |
| references/testing-debug.md | markdown | 3.2 KB |
references/diagnostic-tools.md
View on GitHub# Diagnostic Tools
## Table of Contents
- [Runtime Diagnostics (GODEBUG)](#runtime-diagnostics-godebug)
- [Go documentation command](#go-documentation-command)
- [GC Tracing](#gc-tracing)
- [Scheduler Tracing](#scheduler-tracing)
- [GOTRACEBACK](#gotraceback)
- [Delve Debugger](#delve-debugger)
- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Common Commands](#common-commands)
- [IDE Integration](#ide-integration)
- [Advanced Analysis](#advanced-analysis)
## Runtime Diagnostics (GODEBUG)
### Go documentation command
Use `go doc`, not `go tool doc`. Go 1.26 removed the old `cmd/doc` / `go tool doc` path. Go 1.27 added `package@version` lookups (`go doc golang.org/x/tools/cmd/stringer@v0.30.0`) and an `-ex` flag that lists executable examples.
### GC Tracing
```bash
GODEBUG=gctrace=1 ./app
```
**Output:**
```
gc 123 @45.67s 4%: 0.8+10+0.3 ms clock, 6+5/10/0 ms cpu, 512->300->150 MB
```
| Field | Meaning |
| ---------------- | ----------------------------------------------- |
| 4% | GC CPU overhead (if >10%, over-allocating) |
| 512->300->150 MB | Heap at GC start -> heap at GC end -> live heap |
| Large pause | Allocation storm |
### Scheduler Tracing
```bash
GODEBUG=schedtrace=1000,scheddetail=1 ./app
```
| Signal | Meaning |
| -------------------- | ---------------------------------- |
| runqueue high | CPU saturation, goroutines waiting |
| idleprocs=0 | Fully busy, at capacity |
| spinningthreads | Lock contention |
| threads > gomaxprocs | Blocking syscalls |
### GOTRACEBACK
Get full stack traces on panic:
```bash
GOTRACEBACK=all ./app
```
| Level | Shows |
| -------- | ------------------------------------- |
| `none` | No stack traces |
| `single` | Current goroutine only (default) |
| `all` | All goroutines (useful for deadlocks) |
| `system` | All goroutines + runtime frames |
---
## Delve Debugger
### Installation
```bash
go install github.com/go-delve/delve/cmd/dlv@latest
```
### Basic Usage
```bash
dlv debug ./cmd/myapp # debug a program
dlv test ./mypackage # debug a test
dlv attach 12345 # attach to running process
dlv exec ./myapp -- --flag=v # execute binary with args
```
### Common Commands
```
break main.main # set breakpoint
break file.go:42 # break at line
continue # continue execution
next # step over (n)
step # step into (s)
stepout # step out
print variable # print variable
locals # print all locals
args # print function arguments
goroutines # list all goroutines
goroutine 5 # switch to goroutine 5
stack # show stack trace
```
### IDE Integration
**VS Code:**
```json
// .vscode/launch.json
{
"version": "0.2.0",
"configurations": [
{
"name": "Launch Package",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}",
"env": { "GOTRACEBACK": "all" }
}
]
}
```
**GoLand:** Run -> Edit Configurations -> Go Build. Click gutter to set breakpoints. Use Debugger tab.
---
## Advanced Analysis
→ See `samber/cc-skills-golang@golang-benchmark` skill (compiler-analysis.md) for detailed guides on escape analysis interpretation, assembly inspection, and compiler diagnostics (SSA dump, inlining decisions). See also trace.md for execution tracer analysis.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |