← Community

Write structured logs

Log events as queryable key-value records with a request id threaded through, so an incident is answered with a query instead of grep. Use when adding logging, debugging production, or when logs are unsearchable.

---
name: write-structured-logs
category: coding
description: >-
  Log events as queryable key-value records with a request id threaded through,
  so an incident is answered with a query instead of grep. Use when adding
  logging, debugging production, or when logs are unsearchable.
---

# Write Structured Logs

Prose logs are written for a human reading a terminal. Production logs are read
by a query engine at 3am across a million lines from twelve instances. Those are
different jobs, and the first format cannot do the second.

```
2026-03-14 09:22:01 ERROR Failed to process order for user 8891 after 3 retries
```

You cannot ask that: how many orders failed in the last hour, for which users,
on which host, at what latency. Every answer needs a new regex.

```json
{"ts":"2026-03-14T09:22:01Z","level":"error","event":"order.process.failed",
 "order_id":4471,"user_id":8891,"attempts":3,"duration_ms":812,
 "error":"upstream_timeout","request_id":"7f3a2b","host":"web-02"}
```

Now it is `event:order.process.failed | count by error` — one query, seconds.

Shared publicly by the author and open for any use. See the Terms.