go-observability-review

Go Observability Review

Purpose

Find observability defects in Go code: logging anti-patterns, trace context breaks, metrics cardinality risks, and span lifecycle errors. This skill covers one dimension only — do not report security, concurrency, or error-handling issues outside observability scope.

When To Use

• Any Go change that imports go.uber.org/zap, log/slog, go.opentelemetry.io/, github.com/prometheus/client_golang, github.com/rs/zerolog
• Diffs adding span creation, metric registration, or logging calls
• Files under observability/, telemetry/, instrumentation/, metrics/, tracing/

When NOT To Use

• Non-Go code
• Changes with no logging/tracing/metrics imports or patterns
• Security review of authentication logic → go-security-reviewer

Mandatory Gates

1) Execution Integrity Gate

Run all 12 grep-gated checklist items BEFORE any semantic analysis. Report the audit line: Grep pre-scan: X/12 items hit, Z confirmed as findings (2 semantic-only)

2) Anti-Example Suppression Gate

BEFORE reporting any finding, check against the false-positive rules in references/go-review-anti-examples.md. Apply all matching suppression rules. Suppressed items must appear in the Suppressed Items section with reason.

3) Generated Code Exclusion Gate

Skip these files entirely — do not grep or analyze: *.pb.go, *_gen.go, mock_*.go, wire_gen.go, *_string.go, any file starting with // Code generated

Grep-Gated Execution Protocol

For each grep-gated item: run the grep, record HIT or MISS.

• HIT → proceed to semantic confirmation before reporting
• MISS → mark NOT FOUND, move to next item (no semantic analysis needed)

Never skip a grep step because an earlier item already found issues.

# Item 1: fmt.Print* as logging (exclude test files)
grep -rn 'fmt\.Print' --include='*.go' --exclude='*_test.go' <files>

# Item 2: stdlib log (unstructured, no levels)
grep -rn 'log\.Print\|log\.Println\|log\.Printf\|log\.Fatalf\|log\.Fatalln\|log\.Fatal\b' <files>

# Item 3: logger without context propagation
grep -rn 'zap\.L()\|zap\.S()\|slog\.Info(\|slog\.Warn(\|slog\.Error(\|slog\.Debug(' <files>

# Item 4: context.Background()/TODO() in function bodies (potential chain break)
grep -rn 'context\.Background()\|context\.TODO()' <files>

# Item 5: tracer.Start without nearby defer span.End()
grep -rn '\.Start(ctx,' <files>

# Item 6: span.End() without RecordError or SetStatus
grep -rn 'span\.End()' <files>

# Item 7: Prometheus WithLabelValues (check for variable args)
grep -rn 'WithLabelValues(' <files>

# Item 8: sensitive field names in log calls
grep -rn '"password"\|"passwd"\|"token"\|"secret"\|"credential"\|"api_key"\|"apikey"' <files>

# Item 9: log.Fatal outside main package
grep -rn 'log\.Fatal\b\|log\.Fatalln\|log\.Fatalf' --include='*.go' <files>

# Item 10: HTTP handler logging without request context
grep -rn 'func.*http\.ResponseWriter.*\*http\.Request' <files>

# Item 11: zap.Error(err) as sole field (missing correlation)
grep -rn 'zap\.Error(err)' <files>

# Item 12: Prometheus metric registered against default registry
grep -rn 'prometheus\.MustRegister\|prometheus\.Register(' <files>