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

Human-Readable vs Machine-Parseable

Use structured formats for aggregation but ensure messages remain understandable when reading raw logs.

Human-Readable vs Machine-Parseable

What you'll learn: How to format logs so machines can aggregate them efficiently while humans can still read them directly when needed.

The Dual Audience Problem

Your logs serve two masters: automated systems that parse millions of log entries per second, and humans debugging production issues at 3 AM. Structured logging (like JSON) makes aggregation and searching trivial, but raw JSON can be painful to read when you're tailing logs in a terminal.

The Balancing Act

Machine-parseable means consistent field names, predictable types, and structured formats (JSON, structured text). This allows log aggregation tools to extract fields, build indices, and run queries efficiently:

{"level":"ERROR","service":"auth","user_id":12345,"msg":"Login failed","timestamp":"2024-01-15T10:30:00Z"}

Human-readable means clear messages, logical ordering, and context that makes sense at a glance:

2024-01-15 10:30:00 ERROR [auth] Login failed for user_id=12345

The Solution: Both

Modern logging libraries let you configure different outputs:

  • Production aggregation: Pure structured JSON sent to your centralized logging system
  • Local development: Pretty-printed or line-formatted output for human consumption
  • Emergency debugging: Structured fields in a human-scannable format

The key is maintaining structure (consistent field names like user_id, timestamp, level) while ensuring the msg field tells a complete story. A developer reading raw logs should understand what happened without parsing JSON in their head.

Think of it like a receipt: machines need the barcode (structured fields), but humans need the itemized list (clear messages).

Key Takeaway: Use structured formats for machine aggregation, but ensure log messages remain self-explanatory and context-rich so engineers can understand them when reading raw output during incidents.