go-logging

Go Logging

Logs are written for operators — the human who will be paged at 3 a.m. and needs to know what happened. Every log line either helps diagnose a production issue or it is noise. log/slog from the standard library is the default; reach for anything else only after measuring.

This skill covers logging only. Metrics, distributed tracing, profiling, and RUM are a separate concern — they belong to a future go-observability skill. Do not confuse them with logging here.

Core Rules

1. Use log/slog for new code. Structured, leveled, in the standard library since Go 1.21.
2. Static message, structured fields. The message describes what happened; data goes in key-value attributes.
3. Log or return, never both. Logging a wrapped error makes the same failure appear at every layer.
4. Log at the boundary. HTTP handlers, job runners, and main log. Library code wraps and returns.
5. Use snake_case keys consistently across the codebase (user_id, request_id, elapsed_ms).
6. slog.Error always carries an "err" attribute. Without it, you logged a sentence, not an error.
7. Never log secrets, PII, or unbounded data. Tokens, full credit cards, request bodies — none of it.

Choosing a Logger

Situation	Use
New production service	log/slog
Trivial CLI / one-off script	log (the standard package)
Measured hot-path bottleneck where slog dominates the flame graph	zap or zerolog, but keep the structured style
Existing zap/logrus/zerolog code	Migrate to slog with a bridge handler; see references/slog-handler-ecosystem.md

slog's API is stable, the ecosystem has consolidated around it, and JSON output works with every log shipper. Do not introduce a third-party logger without a benchmark showing the win.

Structured Logging

Build log messages from a static message plus typed fields:

// Good — static message, structured fields
slog.Info("order placed", "order_id", orderID, "total_cents", totalCents)

// Bad — dynamic data baked into the message string
slog.Info(fmt.Sprintf("order %d placed for $%.2f", orderID, total))