Structured logging
Also known as: JSON logging, semantic logging, structured logs
Structured logging means writing log entries as consistent, named fields, usually in JSON, rather than as free-form sentences.
Instead of 'User 42 failed to log in,' a structured log records user_id: 42 and event: login_failed. While it looks like a small formatting change, it turns logs from something humans scroll through into data machines can query, which matters enormously at scale.
Structured logging, explained at three levels
At home
Imagine keeping a diary as a messy paragraph versus filling in a form with labelled boxes: date, place, mood. The form is much easier to search later. Structured logging is the form version for software.
At work
Structured logs make it easy to answer questions like 'how many payment errors did customers in Ontario see yesterday?' without writing complex search patterns. That speeds up troubleshooting and reporting.
At home
A structured log entry might look like a JSON object with fields for time, level (info, warning, error), message, and extra details such as user ID or order number. Every entry uses the same field names, so tools can filter and count them.
At work
Teams agree on standard field names across services, include a trace ID to link logs with distributed traces, and use logging libraries that add context automatically. Log platforms can then build dashboards and alerts directly from fields.
At home
Structure makes it easier to log too much, including personal information, because adding a field is so easy. In my view, structured logging needs a rule for which fields are allowed, especially for passwords, tokens, and health or financial data.
At work
Define a shared schema (OpenTelemetry semantic conventions or the Elastic Common Schema are common starting points), redact sensitive fields at the library level, and control cardinality to keep indexing costs in check. Consider sampling noisy debug logs while keeping all errors. Structured logs also improve audit trails for compliance.
Real-world examples
At home
Aisha's hobby web app kept crashing at random. After switching to structured logs, she filtered by error type and request path in seconds and saw every crash came from one image upload page.
At work
Fatima manages operations at a Calgary logistics company. A regulator asked for every failed delivery notification over six months. Because the logs were structured, her analyst ran one query instead of spending days parsing text files.
How it compares
| feature | Structured logging | Plain-text logging |
|---|---|---|
| Format | Named fields, often JSON | Free-form sentences |
| Searching | Filter by exact fields | Text search and patterns |
| Human readability | Needs a viewer for comfort | Easy to read directly |
| Analysis at scale | Fast and reliable | Slow and error-prone |
Structured logs are written for machines first, which ultimately helps humans too.
For analysts
Logs are often the evidence in audits and incident reviews. I'd agree on standard fields and a list of forbidden ones, like passwords and health data, before rolling structured logging out, because fixing leaked data later is far harder.
History & origin
Unix systems standardized on syslog in the 1980s, which recorded mostly free-text messages. As log volumes exploded with web services, teams relied on fragile regular expressions to extract meaning. The syslog standard RFC 5424, published in 2009, added structured data fields, and libraries such as Logback, Serilog, and Go's zap made JSON logging easy in the 2010s. Log platforms such as Splunk, the ELK stack, and later cloud services rewarded structured data with faster search. Go added structured logging to its standard library with log/slog in 2023, and OpenTelemetry defined a common log data model. In my opinion, any team still parsing free-text logs with regular expressions is paying a tax every day.