Logs

One physical line records one event. Four fields carry it, and nothing else: [time][group_uid][sender] details

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

05Limits

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.
TIME → 02:55:03 02:55:07 02:55:37 c1a0root root c7f3a91k cd8e5vqp no end event — still open group_spawn group_spawn server_begin v1.2.3 port=8080 request_begin GET /api/users request_end_error 30.014s status=500 reason=db_timeout db_query_begin name=select_users db_query_end_error 30.001s ETIMEDOUT

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_exit for 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.