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.