Observability

Structured logging versus plain text logs

When to use structured logging and when plain text logs still make sense for developers and operations

Structured logging versus plain text logs

Logging is the primary way applications tell you what happened during execution. Choosing how to emit logs affects how quickly you find issues, how reliable alerts become, and how well metrics and traces connect to events.

Structured logging is the right fit for production services that need reliable alerts and fast troubleshooting. Plain text logs are fine for small scripts and local debugging.

I switched a mid sized analytics service from plain text to structured logs and the day to day difference was immediate. Searches got faster and noisy alerts dropped.

What is structured logging

Structured logging means emitting log entries as structured data instead of free form sentences. JSON is the most common format, and following consistent conventions makes entries far more useful (see JSON logging best practices). Each log entry contains fields such as timestamp, level, service name, request id, and any contextual values that matter for observability.

Example structured log entry

{"timestamp":"20260505T143045Z","level":"error","service":"orders","requestId":"req_12345","message":"Database connection failed","retry":true}

Because each entry is a data object you can index fields, filter large data sets quickly, and build precise alerts based on specific fields.

What is plain text logging

Plain text logs are human oriented strings written to standard output or files. They are easy to produce and read by developers but the format relies on parsing when machines need to act on log data.

Example plain text log entry

20260505T143045Z ERROR orders Database connection failed requestId=req_12345 retry=true

Plain text logs are compact and familiar. They work well for simple applications and for local debugging when a developer opens logs directly.

Advantages of structured logging

  1. Queryability: With fields you can search and aggregate on specific keys such as request id, user id, or error code without brittle regex parsing.
  2. Better automation: Alerts and dashboards can rely on typed fields, reducing false positives and improving signal to noise.
  3. Easier correlation: Adding trace id and request id fields makes it simple to tie logs to traces and metrics across distributed systems, which is where structured logging pays off most when paired with distributed tracing.
  4. Richer context: Attach contextual objects such as user metadata or feature flags without losing machine readability.

Trade offs and costs

  1. Increased volume: Structured entries are larger than minimal text only messages, which can raise storage and ingestion costs.
  2. Tooling requirements: To get value you need logging infrastructure that understands structured entries, such as search engines or log pipelines.
  3. Developer ergonomics: Structured logs require discipline to include the right keys and avoid noisy fields that dilute usefulness.

When plain text logs are still appropriate

  1. Small utilities and scripts: For short lived scripts or quick automation, human readable messages are fine.
  2. Local debugging: When a developer is working on a laptop and reading files directly, plain messages are faster to scan.
  3. Environments with no structured ingestion: If you lack a log pipeline or search tool and cannot afford the cost to ingest rich entries, plain logs may be pragmatic.

Migration guidance

  1. Start by adding structured fields while preserving your existing message field: Emit both a message string and structured fields so humans and machines can use the same entry.
  2. Standardize keys: Define a minimal schema for timestamp, level, service, request id, user id and error code. Request id and trace id are related but not interchangeable (see correlation IDs versus trace IDs), so keep both if your system generates them separately.
  3. Sample and compress: Use sampling and compression for high volume sources such as batch jobs or debug level traffic.
  4. Add parsing rules and enrichers: Use a log pipeline to enrich entries with environment and deployment metadata and to normalize timestamps and level names. The OpenTelemetry logs documentation is a solid reference if you’re building this pipeline from scratch.

FAQ

Does structured logging increase storage costs? Yes, structured entries are typically larger than minimal text messages. Sampling, compression, and selective enrichment keep ingestion and storage costs under control.

Can I emit structured fields and keep a human readable message? Yes, emit a message field alongside structured keys. That preserves readability while enabling machine queries.

Will structured logging slow my application? Properly implemented structured logging has negligible impact. Avoid expensive synchronous serialization at hot paths and consider async batching for high throughput services.

How do I avoid leaking sensitive data in logs? Apply field level filtering and redaction in your log pipeline. Never serialize full request bodies or raw headers without explicit rules and approval.

What minimal fields should I include in every entry? Include timestamp, level, service name, request id or trace id, and a short message. Add user id or error code when relevant. The Elastic Common Schema reference is a useful starting point if you want a field naming convention instead of inventing your own.

How do I search logs without a structured ingestion tool? If you cannot ingest structured entries, use stable key=value patterns in your message string and ensure timestamps and ids are present for correlation.

Quick examples

Structured logger example in pseudocode

logger.info({
  "timestamp": "20260505T143100Z",
  "service": "payments",
  "level": "info",
  "message": "Payment processed",
  "userId": "user_42",
  "amount": 49.95
})

Plain text logger example in pseudocode

log.info("20260505T143100Z INFO payments Payment processed userId=user_42 amount=49.95")

Recommendation

For most production systems, structured logging is the better default. It shortens incident response time, cuts down false alerts, and plugs directly into observability platforms like log search and tracing tools. Reach for plain text logs when you’re working on something small, local, or in an environment without a log pipeline to ingest structured data.

Getting started note

Add a minimal set of structured fields and keep the human message. For a small service this change often takes an hour. For medium services expect a day for rollout and validation. For large fleets plan a staged rollout and validation over several days.

Measure ingestion cost and tune sampling so you get the benefits without unexpected expense.

Written by the Workshelve team, who write practical explainers on data integrity, networking, and developer tooling.

Top