Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YShymaPrXmc3KYRUg2HMSs
49 lines
2.8 KiB
Markdown
49 lines
2.8 KiB
Markdown
# WS-B — journal source
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Status | Review |
|
|
| 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<JournalEntry>`:
|
|
- 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.
|
|
- 2026-10-15: Implemented B1-B6 on branch ws-b/journal-source. Query and follow verified on the live host. Unit filter matches `_SYSTEMD_UNIT` only; `UNIT` is used only as a fallback when mapping entries. Follow applies backpressure (no drops). `since` is applied during the backward backlog scan.
|