doc updates
This commit is contained in:
1 parent
7e1bd4a9a4
commit
a511ff532e
26 files changed
+573
-770
No files matched your search
@@ -0,0 +1,49 @@
|
||||
# WS-B — journal source
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Done |
|
||||
| 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.
|
||||
- 2026-10-15: Review fixes: unit filter is now (_SYSTEMD_UNIT=u OR UNIT=u), with PRIORITY matches repeated per disjunct. Verified against `journalctl -u hyprland-headless.service` style PID1 lines (same 5 entries, same timestamps). Offline unit tests cover match plan, ordering, `since`, and send exit on drop/cancel. Live follow tests are #[ignore]: `cargo test -- --ignored live_`.
|
||||
Reference in new issue
Block a user