Log Messages: Context and Clarity
You'll learn how to write log messages that help responders diagnose problems quickly with complete context and actionable information.
Why Log Message Quality Matters
When something breaks at 3 AM, your log messages become the primary investigative tool. A vague log like "Error processing request" forces engineers to dig through code, correlate timestamps, and guess what happened. A clear log like "Payment processing failed for order_id=12345, user_id=67890, amount=$99.99, error=insufficient_funds, payment_gateway_response_time=5200ms" tells the complete story instantly.
Essential Elements of Good Log Messages
Include Identifiers
Every log should include correlation IDs, request IDs, user IDs, or transaction IDs that let you trace the flow across services. Without these, you're reading isolated sentences with no narrative thread.
Analogy: It's like a detective finding clues without case numbers—you can't connect evidence to specific incidents.
Provide Context
Include relevant business and technical context: what operation was attempted, what entity it affected, what the input values were, and what state the system was in.
Make It Actionable
Describe what happened and what it means. Instead of "Database error", write "Database connection pool exhausted (50/50 connections in use), query timeout after 30s, table=orders". The responder immediately knows the problem and potential remediation.
Use Structured Fields
Include key-value pairs that can be indexed and searched: user_id=123 action=purchase status=failed reason=card_declined.
Avoid Ambiguity
Be specific. "Request failed" could mean anything. "HTTP 503 from payment-service after 5000ms, circuit breaker opened" is precise.
Key Takeaway: Log messages should tell a complete, searchable story with identifiers, context, and actionable details—write them imagining you'll debug them half-asleep at 3 AM.