Expand description
The diagnostic log: write-only, five levels, three required fields.
The design this implements is docs/logging.md.
Decision and recovery logic reads no log output. That rule is held by shape rather than by discipline: this surface has write methods and no read method, so reading a line back inside the code cannot be spelled. The consequence is the one the design cares about — deleting every log leaves behaviour, replay and totals byte-identical, because nothing downstream could have depended on them.
A line carries seq and never a timestamp. The Ledger position is
what anchors a log line to the only history, and it is an integer
two timelines can be lined up on; a wall clock sampled here would
also be a second sampling point in a library that is not allowed one.
A sink that wants a clock is free to add one — the assembly layer is
where sampling is sanctioned.
A sink receives an Entry rather than a rendered line, because a
sink that had to read the fields back out of the text would be a
second authority on what a line is made of. render is the one
way text is produced, and a sink that wants text calls it.
Structs§
- Diagnostics
- The write-only logging surface.
- Entry
- One line, before anything has decided what it looks like.
- Site
- The three fields every line carries. Required rather than optional: a line that cannot be placed in the history is a line nobody can act on later.
Enums§
- Level
- Who reads a line, and when. Ordered from the widest audience to the narrowest: a floor admits every level at or before it.
Functions§
- render
- One JSON object per line, for the same reason the wire format is: the receiver may be a browser, and a person can still read it.
Type Aliases§
- Sink
- Where lines go. A closure rather than a trait: this crate opens no files, and one implementation is not a seam.