Course contentsShow
← System Design
Lesson 1130 of 1,91929. Observability: LoggingFree lesson

Log Messages: Context and Clarity

Writing informative log messages that include sufficient context, actionable information, and clear descriptions of events.

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.