Structured Logging
Logs you can query beat logs you can only read. Emit structured events with consistent fields, not free-form prose.
What you'll learn
- Contrast free-text logging with structured, key-value events
- Choose a consistent field schema across services
- Set log levels that aid triage rather than noise
- Keep logs useful without leaking sensitive data
6 min
From prose to events
A line like User login failed for bob reads fine to a human but is hard to query at scale. A structured event records the same fact as fields — an event name, a user reference, an outcome, and a reason — so you can filter by any of them across millions of lines. The shift from prose to events is what makes logs searchable rather than merely readable.
Most languages have a structured-logging library that emits JSON or a similar machine format. Adopt one early. Retrofitting structure onto a codebase full of print statements is tedious, and inconsistent formats undermine every dashboard you later try to build.
Agree on a field schema
Consistency is the whole point. Decide on a small set of standard keys and use them everywhere: a timestamp, a level, a service name, an event name, and a correlation identifier. Adding per-event fields is fine; renaming the same concept five different ways is not.
{
'ts': '2026-06-29T04:12:09Z',
'level': 'warn',
'service': 'orders',
'event': 'payment_declined',
'correlation_id': 'a1b2c3',
'reason': 'insufficient_funds'
}Document the schema somewhere your whole team can see it, and prefer adding a new field to overloading an existing one with a second meaning. A field whose contents depend on context is a field your dashboards cannot trust. Pairing every log line with a correlation identifier lets you reconstruct a whole request from scattered services, turning a pile of disconnected lines into a single ordered story you can follow end to end.
Levels that mean something
Use levels to signal urgency, not volume. Reserve error for conditions a human must eventually look at, warn for recoverable anomalies, and info for notable business events. Push verbose tracing to debug so it can be enabled on demand without drowning production.
A common anti-pattern is logging routine success at error or, worse, logging the same failure at three levels from three layers. Decide where a given fact is logged, log it once, and let the correlation identifier connect it to the surrounding context rather than repeating it.
Log facts, not secrets
Structured logs are easy to ship to shared systems, which makes leaking sensitive data easy too. Never log full card numbers, passwords, access tokens, or unredacted personal information. Log a reference — an internal identifier or a masked value — that lets you investigate without exposing the raw data.
Build redaction into your logging layer rather than trusting every call site to remember. A single helper that strips known sensitive keys before serialisation is far safer than dozens of developers hand-editing each log call. See handling personal information for the wider obligations.
Key takeaways
- Emit structured key-value events, not free-form text
- Standardise a small core schema and reuse it everywhere
- Use log levels to signal urgency, and log each fact once
- Always include a correlation identifier
- Redact secrets and personal data in the logging layer
FAQ
Will structured logging slow my application down?
The overhead is small, and asynchronous log shipping keeps it off the request path. The time saved during an incident, when you can query instead of grep, vastly outweighs the cost.
JSON logs are hard to read in a terminal — is that a problem?
Use a pretty-printer locally for human reading while shipping JSON to your aggregation system. You get readability in development and queryability in production.
How long should I keep logs?
Long enough to investigate incidents and meet any retention obligations, but no longer. Indefinite retention of detailed logs increases both cost and the impact of any future data exposure.
Ready to build?
Read the API reference, grab the OpenAPI spec, and ship a resilient integration.