01Log line format
[2026-08-17T02:55:07.000Z][cd8e5vqp][db_query_begin] name=select_users
timeISO-8601 UTC, ms
group_uidunit of work
senderthe one call site
detailsterse, single line
- File
- [2026-08-17T02:55:07.000Z][cd8e5vqp][db_query_begin] name=select_users
- Docker
- [cd8e5vqp][db_query_begin] name=select_users ← the runtime timestamps the line
02Examples one request that times out, then a worker that runs twice
[2026-08-17T02:55:03.000Z][c1a0root][group_spawn] [2026-08-17T02:55:03.000Z][c1a0root][server_begin] v1.2.3 port=8080 [2026-08-17T02:55:07.000Z][c7f3a91k][group_spawn] parent=c1a0root [2026-08-17T02:55:07.000Z][c7f3a91k][request_begin] GET /api/users [2026-08-17T02:55:07.000Z][cd8e5vqp][group_spawn] parent=c7f3a91k [2026-08-17T02:55:07.000Z][cd8e5vqp][db_query_begin] name=select_users [2026-08-17T02:55:37.000Z][cd8e5vqp][db_query_end_error] 30.001s ETIMEDOUT [2026-08-17T02:55:37.000Z][c7f3a91k][request_end_error] 30.014s status=500 reason=db_timeout
The same worker twice, with no [time] — here the runtime adds it:
[c9k2vf3p][group_spawn] [c9k2vf3p][mp4gif_worker_begin] [c9k2vf3p][mp4gif_worker_end_ok] 4.512s [c7t0xb1m][group_spawn] [c7t0xb1m][mp4gif_worker_begin] [c7t0xb1m][mp4gif_worker_end_error] 0.884s ffmpeg exit=1
03Legend
[time]
ISO-8601 UTC with milliseconds; dropped when a collector adds it
group_uid
one unit of work — request, job, cron run
[sender]
one call site, unique in the whole codebase
group_spawn
opens a group; parent= names the caller's group
group_exit
optional close; after it, no producer emits for that group
_begin
operation start
_end_ok
completed successfully
_end_error
completed with an error
spawn relation — happened inside the parent group
04Rules
- A line carries time, group_uid, sender, details — nothing else. Elapsed time, status, and every other measurement belong in
details. timeis required when writing to a file, and omitted when the runtime already timestamps the line, as docker does.- Every event belongs to a group: one request, job, or cron run. The uid is opaque, usually a cuid.
- A group opens with
group_spawn, emitted synchronously before the uid is passed anywhere:- [new_group_uid][group_spawn] parent=old_group_uid
- Omit
parent=for a root group. A receiver uses the caller's uid as the parent of its new group.
senderidentifies one logging call site. The name is unique in the whole codebase, so a grep lands on one place. It is snake_case and matches^[a-z_][a-z0-9_]*$.- A
_beginevent is closed by the same stem:_end_ok— completed successfully_end_error— completed with an error_end— the outcome itself, such as an HTTP status, already says what happened
group_exitis optional and mainly detects leaks. Its absence makes no claim, and consumers must accept groups without it.
05Limits
- Try to keep one line under 2k UTF-8 bytes.
- A log line describes an event; it is not payload storage.
detailsnever contains a physical newline.
Never in a line
- secrets and tokens
- signed URLs and URL query values
- request or response bodies, headers
Log a reference to the payload instead of the payload.
06Visualization
- One lane per group_uid.
- group_spawn draws the parent → child arrow.
- An event sits on the axis at its own time.
- Suffixes give each lane its start and its outcome.
- A lane with no end event is still open — group_exit is optional.
07Tree view
c1a0root group_spawn ├─ server_begin v1.2.3 port=8080 ├─ c7f3a91k group_spawn │ ├─ request_begin GET /api/users │ ├─ cd8e5vqp group_spawn │ │ ├─ db_query_begin │ │ └─ db_query_end_error │ └─ request_end_error └─ (no group_exit)
Summary per group
| group_uid | parent | status | duration | children |
|---|---|---|---|---|
| c1a0root | — | OPEN | — | c7f3a91k |
| c7f3a91k | c1a0root | ERROR | 30.014s | cd8e5vqp |
| cd8e5vqp | c7f3a91k | ERROR | 30.001s | — |
Every column here is read back from the lines themselves. A duration comes from the details of the closing event, never from a field of its own.
08Details: value encoding
bare name=select_users exit=1 ETIMEDOUT 4.512s quoted "no space left on device" "line one\n" "" json {"beta":true} [1,2,3] null counted 3:[180,783,846] 2:["bar","foo"] 0:[] truncated {"name":"asparagus","qua...+4821
- bare — a printable ASCII word without spaces, double quotes, backslashes, or square brackets. A bare value is exactly the bytes that were sent: it cannot span words, break the line, or mint a fake
[tag]. - quoted — every other string is JSON-quoted, so newlines and control characters are escaped, and an empty value stays visible as
"". - json — arrays, objects, booleans, and null use compact JSON.
- counted — an unordered list is sorted and prefixed with its count. Ordered values are never sorted.
- truncated — truncation preserves valid UTF-8 and ends with the number of omitted bytes.
After group_exit
- "After" means producer emission order — not timestamp, not collector ingestion order.
- Buffering may deliver an older event later; that alone is not an error.
- A parent may emit
group_exitfor work it abandons, such as a child that timed out. - Cross-process detection needs preserved per-group order, a shared sequence, or another causal-order signal. Without one it is advisory.