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/production-debug.md
View on GitHub# Production Debugging
## Table of Contents
- [Production Debugging Checklist](#production-debugging-checklist)
- [Step 1: Capture Immediately (don't restart!)](#step-1-capture-immediately-dont-restart)
- [Step 2: System Metrics](#step-2-system-metrics)
- [Step 3: Analyze Locally](#step-3-analyze-locally)
- [Logging & Observability](#logging--observability)
- [Strategic Log Placement](#strategic-log-placement)
- [Structured Logging (Go 1.21+)](#structured-logging-go-121)
- [Request ID Tracing](#request-id-tracing)
- [Network & HTTP Debugging](#network--http-debugging)
- [HTTP Client Issues](#http-client-issues)
## Production Debugging Checklist
When paged for a production issue:
### Step 1: Capture Immediately (don't restart!)
Capture all profiles before restarting the process. The curl commands in [pprof.md](./pprof.md) can be used targeting your production server address. At minimum, capture: goroutine dump (`?debug=2`), heap, CPU (30s), and mutex profiles.
### Step 2: System Metrics
```bash
ps aux | grep myapp
lsof -p PID | wc -l # file descriptors
ss -s # socket summary
netstat -an | grep ESTABLISHED | wc -l
```
### Step 3: Analyze Locally
Download the captured `.prof` files and analyze with `go tool pprof` (see [pprof.md](./pprof.md)).
---
## Logging & Observability
### Strategic Log Placement
Place logs at **component boundaries**, not sprinkled randomly. The goal is to see data entering and exiting each layer, so you can identify exactly which component corrupts or drops it:
```go
// 1. Function entry/exit with key parameters
func ProcessOrder(ctx context.Context, orderID string) error {
log.Printf("ProcessOrder: start orderID=%s", orderID)
defer log.Printf("ProcessOrder: done orderID=%s", orderID)
// ...
}
// 2. Before and after external calls
log.Printf("calling payment API for order %s", orderID)
resp, err := paymentClient.Charge(ctx, req)
if err != nil {
log.Printf("payment API: err=%v", err)
} else {
log.Printf("payment API: status=%d", resp.StatusCode)
}
// 3. At decision points
if user.IsAdmin {
log.Printf("admin path for user %s", user.ID)
}
```
### Structured Logging (Go 1.21+)
```go
import "log/slog"
slog.Info("processing request",
"method", r.Method,
"path", r.URL.Path,
"user_id", userID,
)
slog.Error("database query failed",
"err", err,
"query", query,
"duration_ms", elapsed.Milliseconds(),
)
```
### Request ID Tracing
```go
type ctxKey string
func WithRequestID(ctx context.Context, id string) context.Context {
return context.WithValue(ctx, ctxKey("request_id"), id)
}
func RequestID(ctx context.Context) string {
id, _ := ctx.Value(ctxKey("request_id")).(string)
return id
}
```
---
## Network & HTTP Debugging
### HTTP Client Issues
```go
// 1. HTTP clients MUST set timeouts — default http.Client has NO timeout
client := &http.Client{
Timeout: 30 * time.Second,
Transport: &http.Transport{
DialContext: (&net.Dialer{Timeout: 5 * time.Second}).DialContext,
TLSHandshakeTimeout: 5 * time.Second,
IdleConnTimeout: 90 * time.Second,
MaxIdleConns: 100,
MaxIdleConnsPerHost: 10,
},
}
// 2. Response body MUST be closed
resp, err := client.Do(req)
if err != nil {
return err
}
defer resp.Body.Close()
// 3. Read body on error status (for error messages from server)
if resp.StatusCode >= 400 {
body, _ := io.ReadAll(resp.Body)
return fmt.Errorf("API error %d: %s", resp.StatusCode, body)
}
// 4. Dump full request/response for debugging
import "net/http/httputil"
dump, _ := httputil.DumpRequestOut(req, true)
log.Printf("request:\n%s", dump)
dump, _ = httputil.DumpResponse(resp, true)
log.Printf("response:\n%s", dump)
```
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: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | 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 |