Problem
Unstructured text logs are human-readable but machine-opaque. Grep doesn't scale. Correlation across services is manual.
observabilityestablished · low operational burden
Structured Logging
Also known as: json-logging, log-structured, structured-logs
Intent
Emit logs as structured data (JSON) with consistent fields, enabling querying, alerting, and correlation across services.
Forces
- •Logs must be queryable (filter by user, request, error code)
- •Consistent fields across services enable correlation
- •High-volume logging must be performant
- •Human readability still needed for debugging
Solution
✓ When to Use
- •All services in distributed system
- •Centralized log aggregation
- •Alerting on log patterns (error rates, latency)
- •Debugging with correlation to traces
✗ When Not to Use
- •Local development (pretty console output preferred)
- •Extremely high-frequency internal loops (use metrics)
- •Audit logs (separate immutable store)
Pros
- +Queryable: `service=payment AND level=error AND duration>1000`
- +Correlation: join logs with traces via trace_id
- +Alerting: log-based metrics, anomaly detection
- +Standard tooling: Loki, Elasticsearch, Datadog, Splunk
Cons
- −Larger log volume (JSON overhead)
- −Schema discipline required (field naming, types)
- −PII risk: structured fields easier to accidentally log
- −Migration from unstructured is gradual
Cost Profile
Infrastructure
Low — stdout + collector
Operational
Low — standard pipeline
Cognitive
Low — consistent field names
Failure Modes
Field name drift across services (payment_id vs paymentId)
High cardinality labels (user_id) → index explosion
PII in logs → compliance violation
Log burst → collector backpressure, dropped logs
Real-World Examples
Alternatives
- unstructured-text
- structured-metrics
- distributed-tracing
Related Patterns
- distributed-tracing
- metrics
- correlation-id
- pii-redaction
Competency Domains
reliability opssecurity complianceeconomics evolution