logging-best-practices

Structured logging uses JSON key-value pairs instead of string interpolation, for example {"event": "payment_failed", "user_id": "123"}. Every event should include timestamp, level, event name, request_id, service, and environment so logs are machine-parseable and queryable.

Every log event should include an ISO 8601 timestamp, a level (debug, info, warn, error), a snake_case event name, a request_id or trace_id, the service name, and the environment. High-cardinality fields like user_id, org_id, and order_id make logs queryable during incidents.

Pass trace and request IDs through all service boundaries using HTTP headers or message queue metadata, and have downstream services inherit them. Use middleware or interceptors to inject context automatically, and store and restore the original request context for async jobs.

Never log sensitive data such as passwords, tokens, PII, or credit card numbers. Also avoid logging inside tight loops, success cases with no debugging value, and information already captured by infrastructure like load balancer logs.

Use warn when something unexpected happened but the system handled it, such as retries or fallbacks. Use error when something failed and likely needs human attention, such as exceptions or failed requests, and avoid logging errors for expected conditions like a wrong password.