Catalog My learning Blog
Observability Course: Metrics, Logs, Traces, OpenTelemetry · Phase 1 · Lesson 3 · 3 min read

Structured Logging Explained with Examples

On this page
  1. Why plain-text logs don't scale
  2. What is structured logging?
  3. Fields to include on every log line
  4. Structured logging best practices
  5. Check yourself

Why plain-text logs don't scale

JavaScript
console.log(`Order ${orderId} failed for customer ${customerId} (tier: ${tier}): payment gateway timeout after ${elapsedMs}ms`);

That line is fine for a human reading one file. At 50 servers and millions of lines, questions like "how many gateway timeouts per tier in the last hour?" need regular expressions that break whenever someone rewords the message.

What is structured logging?

A structured log is a set of named fields, usually JSON, one event per line. The service from this course's lab logs failures with pino:

Code
logger.error({ event: 'request_failed', route, method, status, duration_ms, order_id, error: 'payment_gateway_timeout' });

And emits:

JSON
{"level":50,"time":1791737542554,"service":"checkout","instance":"checkout-9101",
 "event":"request_failed","route":"/orders/:id/checkout","method":"POST","status":503,
 "duration_ms":33,"order_id":"28689","error":"payment_gateway_timeout"}

Now "failures by error type and route in the last hour" is a filter and a group-by in any log platform (Loki, Elasticsearch, CloudWatch Logs Insights, Datadog), with no parsing. The service and instance fields come from the logger's base configuration, so every line carries them without anyone remembering to add them.

A free-text message mixes data into a sentence; a structured event keeps each value in a named field that can be filtered and aggregated.
A free-text message mixes data into a sentence; a structured event keeps each value in a named field that can be filtered and aggregated.

Fields to include on every log line

FieldWhy
timestamp (UTC, ISO 8601 or epoch ms)Ordering and correlation across services
levelFiltering by severity (Day 4)
service, version, environment, instanceWhich deploy of what, where
eventA stable, machine-friendly name (order_failed), not a sentence
trace_id, span_idJumping from a log to its trace (Day 19)
request_id, user_id or tenant_idFollowing one request or one customer
error.type, error.message, error.stackGrouping failures by kind

OpenTelemetry's semantic conventions give standard names for many of these, so tools understand them without configuration.

Structured logging best practices

  • Stable event names and field names. Treat them like an API: dashboards and alerts depend on them. Rename and you break queries.
  • Consistent types: duration_ms is always a number in milliseconds, never "33ms".
  • Log context once: attach request-scoped fields (trace ID, user) to a child logger at the start of the request, rather than passing them to every call. With pino:
JavaScript
const log = logger.child({ request_id: 'req_8f2a91', user_id: 'u_42' });   // once per request
log.info({ event: 'cart_loaded', items: 3 });
log.warn({ event: 'gateway_retry', attempt: 2 });
JSON
{"level":30,"service":"checkout","request_id":"req_8f2a91","user_id":"u_42","event":"cart_loaded","items":3}
{"level":40,"service":"checkout","request_id":"req_8f2a91","user_id":"u_42","event":"gateway_retry","attempt":2}

Both lines carry the request's fields though neither call mentions them. Store the child logger on the request object (req.log in pino-http does exactly this) so every handler uses it.

  • No secrets or unnecessary personal data: passwords, tokens, card numbers, full request bodies. Redact at the logger level (pino's redact option, for example).
  • One event per line, including multi-line stack traces as a single JSON string.
  • Log to stdout in containers and let the platform collect and ship logs.
  • Make messages human-friendly too: a short msg field helps when reading a single log.

Check yourself

Each value is in a named field, so tools can filter and aggregate directly without fragile parsing of free text.

Dashboards, alerts and saved queries depend on them. Renaming user_id to userId silently breaks those consumers, with no error, until someone needs them during an incident. Agree on a schema, such as OpenTelemetry semantic conventions.

Once, at the start of the request, to a request-scoped child logger or context, so every log line written during that request carries it automatically without each call having to remember.

Create a child logger with those fields once at the start of the request and use it for every log line in that request.

JSON is easy for machines to parse and index. Locally, a pretty-printer can show the same structured logs in a readable format.