zerolog-observability

Structured Logging (Go)

Overview

Logs are for machines first: structured fields you can filter and correlate, not prose. The recurring defects are fmt.Println debugging left in, data interpolated into the message instead of fields, the same error logged at every layer, and secrets leaking into logs.

Core principle: log the failure at its site, with fields, once — and use the repository's own logger.

Which logger

Follow the repository's existing logger: github.com/rs/zerolog, log/slog (stdlib), or go.uber.org/zap all give structured fields and are fine to continue. Use zerolog only when the repo has no logger yet. Never introduce a second logging library alongside one the repo already uses (rule repo-conventions-win). Never fmt.Println / log.Printf in production code regardless of which structured logger the repo picked.

Rules

• Fields, not interpolation: ids and operation names are structured fields, not baked into the message string.

• Correlate with a request-scoped logger, not the global one. Middleware attaches request_id (and relevant entity ids) once and puts the enriched logger in the request's context; handlers and services pull it back out instead of re-adding the id everywhere:

  // middleware, once per request
  l := log.With().Str("request_id", reqID).Logger()
  c.SetUserContext(l.WithContext(c.UserContext()))
  
  // anywhere downstream
  zerolog.Ctx(ctx).Error().Err(err).Str("task_id", id.String()).Msg("dispatch failed")
  

  (slog: slog.Default().With("request_id", reqID) carried the same way via context, or a custom Handler.)

• Handle errors once (samber "single handling rule" / Uber "Handle Errors Once"): an error is either logged OR returned/wrapped, never both. Log-and-return at every layer reports the same failure N times. Log at the site that has the most context (usually where it's finally handled, e.g. the HTTP error mapper), propagate elsewhere with %w and say nothing.

• Never log secrets, tokens, full request bodies, or other PII that may carry user data. Treat user-supplied strings as values only — never splice them into the message template (log injection: a user-controlled newline or field name can forge log entries).