Principle: Logs should tell a story

Logs are either too verbose (noise), too sparse (missing context), or unstructured (hard to follow).

Write logs that help you reconstruct what happened:

Log at transitions, not steps:

# BAD: Too verbose, hard to find important events
logger.info('Starting to process order')
logger.info('Validating order items')
logger.info('Validation passed')
logger.info('Calculating total')
logger.info('Total calculated: 42.00')
logger.info('Charging payment')
logger.info('Payment charged')

# GOOD: Log state transitions with context
logger.info('order_received', extra={'order_id': '123', 'items': 3})
# ... processing ...
logger.info('order_completed', extra={
    'order_id': '123', 'total': 42.00, 'duration_ms': 142
})

Include enough context to debug without reproducing:

# BAD
logger.error('Payment failed')

# GOOD
logger.error('payment_failed', extra={
    'order_id': order_id,
    'amount': amount,
    'provider': 'stripe',
    'error_code': e.code,
    'customer_id': customer_id,
    'idempotency_key': idem_key,
})

Log levels matter:

• ERROR: Something is broken, needs attention now
• WARN: Something unexpected, but handled (degraded mode)
• INFO: Business events (user signed up, order placed)
• DEBUG: Developer details (only enable when debugging)

The story test: Can someone who wasn't there read the logs and understand what happened, why it failed, and what to do about it?

During an incident at 3 AM, logs are your only witness. Good logs tell you what happened, bad logs tell you that something happened.

Writing useful application logs for production debugging