# WS-B — journal source | Field | Value | |---|---| | Status | Backlog | | Owner | — | | Phase | 1 (parallel) | | Depends on | P0 (incl. spike findings on the `systemd` crate) | | Blocks | WS-E, WS-F, WS-G (to finish) | | Owned files | `src/sources/journal.rs`, `examples/journal_tail.rs` | ## Goal Implement `JournalSource` over sd-journal via the `systemd` crate. It provides a bounded snapshot query and a cancellable live follow. ## Tasks Tick these in [`TODO.md`](../../TODO.md). - **B1** Run every sd-journal call inside `tokio::task::spawn_blocking` (review G1). Open the journal inside the blocking closure and never hold it across `.await`. Use `sources.journal_namespace` if the spike found namespace support. Otherwise log a warning when it is set and use the default journal. - **B2** `query(JournalQuery)`: - Unit filter via `match_add("_SYSTEMD_UNIT", unit)`. - Priority filter `≤ N` by adding one `PRIORITY=k` match for each k in 0..=N. Matches on the same field are OR'ed by sd-journal. - `seek_tail`, then step backward `lines` entries. `lines` is clamped to `limits.max_lines`. - Reverse the result so it returns oldest-first. - **B3** `follow(JournalQuery, CancellationToken) -> mpsc::Receiver`: - Seek to tail and run a blocking loop of `wait(Some(500ms))`, then drain new entries with `next`. - Each iteration checks `tx.is_closed()` and `token.is_cancelled()` and exits if either is true (review G2). - Use `blocking_send` with a bounded channel, around 1024 entries. Decide on drop-or-block for slow consumers and document it. - **B4** Map `__REALTIME_TIMESTAMP`, `PRIORITY`, `_SYSTEMD_UNIT`, `SYSLOG_IDENTIFIER`, `_PID`, `_HOSTNAME` and `MESSAGE` to `JournalEntry`. `MESSAGE` may be binary, so convert it with lossy UTF-8. - **B5** `examples/journal_tail.rs --unit X [--priority err] [--lines N] [--follow]`. - **B6** Test that dropping the receiver makes the blocking thread exit within about one second. Use a counter or `JoinHandle` to prove it. ## Done when - The example snapshot output matches `journalctl -u X -p err -n N -o json` for the same filters. - Follow prints new entries live. `logger -t test hello` shows up in under a second. - B6 passes. ## Notes - Reading the full system journal needs the `systemd-journal` group (or root). Without it you only see your own user's entries. Say so in the example's error output. - If the `systemd` crate turns out unmaintained or broken during the spike, record the alternative in the P0 log before starting. ## Log - 2026-10-15: Card created.