go-observability

Go Observability

Observability is not optional for production services. Every service must produce structured logs, expose metrics, and propagate trace context. Use the stdlib log/slog for logging and OpenTelemetry for tracing and metrics.

Detailed reference material, loaded on demand:

• references/slog.md — handler setup, logger injection, child loggers.
• references/tracing.md — tracer provider, spans, propagation, shutdown.
• references/metrics.md — metric definitions, HTTP instrumentation.

Read a reference file only when the section below is not enough.

1. Structured Logging with slog

Use log/slog (Go 1.21+) with a JSON handler in production. Every line is key-value pairs, never a formatted sentence:

// ✅ Good — structured, leveled
logger.Info("user created", slog.String("user_id", user.ID), slog.Duration("latency", elapsed))

// ❌ Bad — unparseable in production
log.Printf("user %s created in %v", user.ID, elapsed)

Inject the logger as a dependency; never reach for a package-level global. Derive child loggers with logger.With(...) so component, method and request ID are attached once instead of at every call site. See references/slog.md.

Log levels — use them consistently

Level	Use for
Debug	Verbose diagnostic info, disabled in production
Info	Normal operations: request received, job completed
Warn	Recoverable issues: retry succeeded, deprecated usage
Error	Failures requiring attention: DB down, external call failed

NEVER log at Error level for expected conditions (user not found → Info or Warn).

Sensitive data — NEVER log

• Passwords, tokens, API keys
• Full credit card numbers, SSNs
• Raw request bodies containing PII

// ✅ Good — redacted
logger.Info("auth attempt", slog.String("user", email), slog.Bool("success", ok))

// ❌ Bad — leaks credentials
logger.Info("auth attempt", slog.String("password", password))

2. Distributed Tracing with OpenTelemetry