Source-Concept Mismatch: Structured Logging

Why it exists

Plain console.log output is a free-text sentence meant for a human reading a single terminal in real time. Once an app runs as many concurrent instances across containers, that terminal no longer exists, and finding one request's logs among millions of interleaved lines by string matching becomes impractical. Structured logging exists to make log lines machine-parseable by default, so searching, filtering, and alerting can run as queries over fields instead of text search over prose.

The mental model

Structured logging is filling out a form instead of writing a sentence. A free-text log spells out, as one sentence, that user 4021 failed checkout because of a Stripe timeout. A structured log says the same thing as named fields: event, level, userId, provider, reason. A form is slower to write by hand but trivial for software to search, sort, and aggregate, which is exactly the tradeoff that matters once logs are read by machines first and humans second.

How it works

A logging library like pino or winston replaces console.log calls with a logger that emits newline-delimited JSON. Express middleware, such as pino-http, generates or reads a correlation id, often from an x-request-id header, and attaches a child logger to the request carrying that id, so every log statement made anywhere while handling that request automatically includes it without threading the id through every function call by hand. Log levels, debug, info, warn, error, let production filter volume without a redeploy. The JSON stream ships to an aggregator like Datadog, the ELK stack, or CloudWatch, which indexes each field so a query for one request id returns that request's entire lifecycle in order.

When it matters

It matters the moment an app runs more than one instance or a production incident needs reconstructing after the fact. The footgun is logging sensitive fields, passwords, tokens, full request bodies, as structured data, which makes them trivially searchable and exportable in the aggregator, often a worse exposure than the same value buried in an unstructured string. Over-logging at info level in a hot path also adds real serialization and shipping cost.

A concrete example

An Express checkout endpoint assigns each request an id via pino-http. When a customer's payment fails, filtering the aggregator by that one request id instantly shows auth passing at 10:02:01, the cart validated at 10:02:02, then a Stripe timeout logged at level error, provider stripe, at 10:02:03, rather than grepping thousands of interleaved lines from concurrent requests.