stark-logging

Use a constant message string with data passed as typed fields, such as log.Error("connector sync failed", "connector", name, "error", err). Interpolated values create unique strings that cannot be aggregated or alerted on.

Choose by whether the operation failed or was handled: a retried timeout that succeeded or a skipped malformed row is WARN, while a failure the code could not paper over is ERROR. Levels reflect audience and required action, not how bad the event feels.

Yes, the rules are language-agnostic and hold for slog, zerolog, zap, pino, structlog, and tracing. The reference implementation uses Go slog, but the principles of constant messages, fields, and level semantics port to any structured logger.

Logging and returning the same error prints it N times at N stack depths, creating duplicate noise. Wrap and return the error deep in the stack, then log it once at the boundary that handles or swallows it.

Never pass tokens, credentials, auth headers, or full request bodies to the logger, and log stable ids instead of emails or names. A handler-level denylist is only a backstop since it cannot catch secrets hidden in messages, error strings, or URLs.

Log levels label events but are not an alerting system; paging should come from SLOs and metrics like error rate and latency. A single ERROR log line is legitimate without paging anyone, so keep alerting and logging concerns separate.