Principle: Logging should tell a story

Logs are either too verbose (noise drowns signal) or too sparse (can't debug production issues). Log messages lack context to reconstruct what happened.

Write logs that let you reconstruct the chain of events:

1. Log at decision points, not every line:

Bad: log('entering function'), log('checking condition'), log('done')
Good: log('Payment declined', { reason, amount, user_id })

1. Include context in every log:

Bad: log('Error processing request')
Good: log('Payment processing failed', {
request_id: 'req-123',
user_id: 'user-456',
amount: 99.99,
error: 'Card declined',
attempt: 2,
})

1. Use appropriate log levels:

ERROR: Something failed that shouldn't have (page someone)
WARN: Something unexpected but handled (monitor trend)
INFO: Business events (user signed up, order placed)
DEBUG: Technical details (query took 150ms, cache hit)

1. Correlation IDs for request tracing:

request_id = uuid4()
logger = logger.bind(request_id=request_id)
# Now every log in this request includes the ID

1. Don't log:

- Passwords, tokens, or PII
- Every iteration of a loop
- Successful health checks
- Info that's already in traces/metrics

1. Test your logs:

Can you find why a customer's order failed using only logs?

Good logs are the difference between a 5-minute fix and a 5-hour investigation. Each log line should move you closer to understanding what happened.