diff --git a/TODO.md b/TODO.md index aa672f9..be52bad 100644 --- a/TODO.md +++ b/TODO.md @@ -36,12 +36,12 @@ Design: [`plan.md`](plan.md) · Review fixes: [`plan/review.md`](plan/review.md) - [ ] **A7** Unit tests for timestamp conversion and property mapping ### WS-B journal · [card](plan/workstreams/WS-B-journal.md) -- [ ] **B1** All sd-journal access inside `spawn_blocking`. Optional namespace, depending on the spike. -- [ ] **B2** `query(filter)`: unit, priority ≤ N, `lines` capped by `limits.max_lines`, returned in chronological order -- [ ] **B3** `follow(filter)` returns an mpsc receiver. `wait()` with a timeout. Exits on receiver drop or shutdown. -- [ ] **B4** Entry mapping with lossy UTF-8 for binary `MESSAGE` -- [ ] **B5** `examples/journal_tail.rs` -- [ ] **B6** Test: the follow thread exits after its receiver is dropped +- [x] **B1** All sd-journal access inside `spawn_blocking`. Optional namespace, depending on the spike. +- [x] **B2** `query(filter)`: unit, priority ≤ N, `lines` capped by `limits.max_lines`, returned in chronological order +- [x] **B3** `follow(filter)` returns an mpsc receiver. `wait()` with a timeout. Exits on receiver drop or shutdown. +- [x] **B4** Entry mapping with lossy UTF-8 for binary `MESSAGE` +- [x] **B5** `examples/journal_tail.rs` +- [x] **B6** Test: the follow thread exits after its receiver is dropped ### WS-C docker · [card](plan/workstreams/WS-C-docker.md) - [ ] **C1** Lazy `bollard::Docker` on the configured socket. Missing or denied socket maps to `Unavailable`. diff --git a/examples/journal_tail.rs b/examples/journal_tail.rs new file mode 100644 index 0000000..a5fdf1f --- /dev/null +++ b/examples/journal_tail.rs @@ -0,0 +1,55 @@ +//! Usage: journal_tail [--unit X] [--priority err] [--lines N] [--follow] +use skyg_linux_tracker::config::Config; +use skyg_linux_tracker::sources::journal::SdJournal; +use skyg_linux_tracker::sources::{JournalQuery, JournalSource, Priority}; +use tokio_util::sync::CancellationToken; + +#[tokio::main] +async fn main() { + let mut q = JournalQuery::default(); + let mut follow = false; + let mut args = std::env::args().skip(1); + while let Some(a) = args.next() { + match a.as_str() { + "--unit" => q.unit = args.next(), + "--priority" => { + let v = args.next().unwrap_or_default(); + match v.parse::() { + Ok(p) => q.priority = Some(p), + Err(e) => die(&format!("bad --priority {v:?}: {e}")), + } + } + "--lines" => match args.next().and_then(|v| v.parse().ok()) { + Some(n) => q.lines = Some(n), + None => die("--lines needs a number"), + }, + "--follow" => follow = true, + other => die(&format!("unknown argument {other:?}")), + } + } + let token = CancellationToken::new(); + let src = SdJournal::new(&Config::default(), token.clone()); + if follow { + let mut rx = src.follow(&q).await.unwrap_or_else(|e| fail(e)); + while let Some(e) = rx.recv().await { + println!("{}", serde_json::to_string(&e).unwrap()); + } + } else { + for e in src.query(&q).await.unwrap_or_else(|e| fail(e)) { + println!("{}", serde_json::to_string(&e).unwrap()); + } + } +} + +fn fail(e: skyg_linux_tracker::error::AppError) -> ! { + die(&format!( + "{}\nhint: reading the full system journal needs the `systemd-journal` group (or root); \ + otherwise only your own entries are visible.", + e.message() + )) +} + +fn die(msg: &str) -> ! { + eprintln!("journal_tail: {msg}"); + std::process::exit(2); +} diff --git a/plan/workstreams/WS-B-journal.md b/plan/workstreams/WS-B-journal.md index d0a6e9b..aa8442d 100644 --- a/plan/workstreams/WS-B-journal.md +++ b/plan/workstreams/WS-B-journal.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Backlog | +| Status | Review | | Owner | — | | Phase | 1 (parallel) | | Depends on | P0 (incl. spike findings on the `systemd` crate) | @@ -45,3 +45,4 @@ Tick these in [`TODO.md`](../../TODO.md). ## 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. diff --git a/src/sources/journal.rs b/src/sources/journal.rs index 91be47d..05356d1 100644 --- a/src/sources/journal.rs +++ b/src/sources/journal.rs @@ -1,36 +1,283 @@ -//! journald source over libsystemd (WS-B owns this file). +//! journald source over libsystemd (WS-B). //! -//! STUB: signatures are final, bodies are `todo!()`. -//! Notes for WS-B: `systemd::journal::Journal` is neither `Send` nor `Sync`. -//! Open it inside `spawn_blocking` and never move it across threads or hold it -//! across an `.await`. Namespaces need `OpenOptions::open_namespace` -//! (feature `systemd_v245`, already enabled). +//! `systemd::journal::Journal` is neither `Send` nor `Sync`, so every +//! sd-journal call happens inside a `spawn_blocking` closure that opens its own +//! handle and drops it before returning. Nothing is held across an `.await`. +//! +//! Slow consumers: `follow` applies backpressure. The producer waits for room +//! in the bounded channel (1024 entries) and never drops entries. While +//! waiting it still notices receiver drop and shutdown. + +use std::time::Duration; use async_trait::async_trait; -use tokio::sync::mpsc; +use jiff::Timestamp; +use systemd::journal::{Journal, JournalRecord, OpenOptions}; +use tokio::sync::{mpsc, oneshot}; +use tokio::task::JoinHandle; use tokio_util::sync::CancellationToken; -use super::{JournalEntry, JournalQuery, JournalSource}; +use super::{clamp_count, JournalEntry, JournalQuery, JournalSource, Priority}; use crate::config::Config; use crate::error::AppError; -pub struct SdJournal {} +const CHANNEL_CAP: usize = 1024; +const WAIT: Duration = Duration::from_millis(500); +const SEND_RETRY: Duration = Duration::from_millis(50); + +pub struct SdJournal { + namespace: Option, + max_lines: usize, + shutdown: CancellationToken, +} impl SdJournal { /// Must not fail or block. Reads `sources.journal_namespace` and /// `limits.max_lines` from `config`. Follow tasks stop on `shutdown`. - pub fn new(_config: &Config, _shutdown: CancellationToken) -> Self { - Self {} + pub fn new(config: &Config, shutdown: CancellationToken) -> Self { + let ns = config.sources.journal_namespace.trim(); + Self { + namespace: (!ns.is_empty()).then(|| ns.to_string()), + max_lines: config.limits.max_lines, + shutdown, + } + } + + /// Start the blocking follow loop. Returns the receiver and the join + /// handle of the blocking thread (used by tests to prove it exits). + async fn spawn_follow( + &self, + q: &JournalQuery, + ) -> Result<(mpsc::Receiver, JoinHandle<()>), AppError> { + let q = q.clone(); + let ns = self.namespace.clone(); + let lines = clamp_count(q.lines, self.max_lines); + let token = self.shutdown.clone(); + let (tx, rx) = mpsc::channel(CHANNEL_CAP); + let (ready_tx, ready_rx) = oneshot::channel(); + let handle = tokio::task::spawn_blocking(move || { + let mut j = match open_filtered(ns.as_deref(), &q) { + Ok(j) => { + let _ = ready_tx.send(Ok(())); + j + } + Err(e) => { + let _ = ready_tx.send(Err(e)); + return; + } + }; + follow_loop(&mut j, &q, lines, &tx, &token); + }); + match ready_rx.await { + Ok(Ok(())) => Ok((rx, handle)), + Ok(Err(e)) => Err(e), + Err(_) => Err(AppError::Internal("journal thread died".into())), + } + } +} + +fn unavailable(e: impl std::fmt::Display) -> AppError { + AppError::Unavailable(format!("journal: {e}")) +} + +/// Open the journal (inside the blocking thread) and apply unit/priority matches. +fn open_filtered(ns: Option<&str>, q: &JournalQuery) -> Result { + let mut opts = OpenOptions::default(); + opts.system(true); + let mut j = match ns { + Some(ns) => opts.open_namespace(ns), + None => opts.open(), + } + .map_err(unavailable)?; + if let Some(unit) = &q.unit { + j.match_add("_SYSTEMD_UNIT", unit.as_str()) + .map_err(unavailable)?; + } + if let Some(p) = q.priority { + // Same-field matches are OR'ed: PRIORITY in 0..=p. + for k in 0..=p.as_u8() { + j.match_add("PRIORITY", k.to_string()) + .map_err(unavailable)?; + } + } + Ok(j) +} + +fn to_entry(j: &mut Journal, rec: JournalRecord) -> JournalEntry { + let ts = j + .timestamp_usec() + .ok() + .and_then(|u| i64::try_from(u).ok()) + .and_then(|u| Timestamp::from_microsecond(u).ok()) + .unwrap_or(Timestamp::UNIX_EPOCH); + JournalEntry { + timestamp: ts, + priority: rec + .get("PRIORITY") + .and_then(|s| s.parse::().ok()) + .and_then(Priority::from_u8), + unit: rec + .get("_SYSTEMD_UNIT") + .or_else(|| rec.get("UNIT")) + .cloned(), + identifier: rec.get("SYSLOG_IDENTIFIER").cloned(), + pid: rec.get("_PID").and_then(|s| s.parse().ok()), + hostname: rec.get("_HOSTNAME").cloned(), + // Values were already lossily decoded by the systemd crate. + message: rec.get("MESSAGE").cloned().unwrap_or_default(), + cursor: j.cursor().ok(), + } +} + +/// Read up to `lines` most recent matching entries, oldest first. +fn read_backlog( + j: &mut Journal, + q: &JournalQuery, + lines: usize, +) -> Result, AppError> { + j.seek_tail().map_err(unavailable)?; + let mut out = Vec::new(); + while out.len() < lines { + let Some(rec) = j.previous_entry().map_err(unavailable)? else { + break; + }; + let e = to_entry(j, rec); + if q.since.is_some_and(|s| e.timestamp < s) { + break; + } + out.push(e); + } + out.reverse(); + Ok(out) +} + +/// Send with backpressure; returns false when the consumer or shutdown ended us. +fn send(tx: &mpsc::Sender, token: &CancellationToken, mut e: JournalEntry) -> bool { + loop { + if token.is_cancelled() { + return false; + } + match tx.try_send(e) { + Ok(()) => return true, + Err(mpsc::error::TrySendError::Closed(_)) => return false, + Err(mpsc::error::TrySendError::Full(back)) => { + e = back; + std::thread::sleep(SEND_RETRY); + } + } + } +} + +fn follow_loop( + j: &mut Journal, + q: &JournalQuery, + lines: usize, + tx: &mpsc::Sender, + token: &CancellationToken, +) { + let backlog = match read_backlog(j, q, lines) { + Ok(b) => b, + Err(e) => { + tracing::warn!(error = %e, "journal backlog failed"); + return; + } + }; + // Resume right after the newest backlog entry (or the tail if none). + let resumed = match backlog.last().and_then(|e| e.cursor.clone()) { + Some(c) => j.seek_cursor(c).and_then(|()| j.next().map(|_| ())), + None => j.seek_tail().and_then(|()| j.previous().map(|_| ())), + }; + if let Err(e) = resumed { + tracing::warn!(error = %e, "journal seek failed"); + return; + } + for e in backlog { + if !send(tx, token, e) { + return; + } + } + loop { + if tx.is_closed() || token.is_cancelled() { + return; + } + if let Err(e) = j.wait(Some(WAIT)) { + tracing::warn!(error = %e, "journal wait failed"); + return; + } + loop { + match j.next_entry() { + Ok(Some(rec)) => { + let e = to_entry(j, rec); + if !send(tx, token, e) { + return; + } + } + Ok(None) => break, + Err(e) => { + tracing::warn!(error = %e, "journal read failed"); + return; + } + } + } } } #[async_trait] impl JournalSource for SdJournal { - async fn query(&self, _q: &JournalQuery) -> Result, AppError> { - todo!("WS-B B2") + async fn query(&self, q: &JournalQuery) -> Result, AppError> { + let q = q.clone(); + let ns = self.namespace.clone(); + let lines = clamp_count(q.lines, self.max_lines); + tokio::task::spawn_blocking(move || { + let mut j = open_filtered(ns.as_deref(), &q)?; + read_backlog(&mut j, &q, lines) + }) + .await + .map_err(|e| AppError::Internal(format!("journal task: {e}")))? } - async fn follow(&self, _q: &JournalQuery) -> Result, AppError> { - todo!("WS-B B3") + async fn follow(&self, q: &JournalQuery) -> Result, AppError> { + self.spawn_follow(q).await.map(|(rx, _)| rx) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// B6: dropping the receiver ends the blocking follow thread within ~1s. + #[tokio::test] + async fn follow_thread_exits_when_receiver_dropped() { + let src = SdJournal::new(&Config::default(), CancellationToken::new()); + let q = JournalQuery { + lines: Some(1), + ..Default::default() + }; + let (rx, handle) = match src.spawn_follow(&q).await { + Ok(v) => v, + Err(e) => { + eprintln!("skipping: journal unavailable: {e}"); + return; + } + }; + drop(rx); + tokio::time::timeout(Duration::from_millis(1500), handle) + .await + .expect("follow thread did not exit") + .unwrap(); + } + + #[tokio::test] + async fn follow_thread_exits_on_shutdown() { + let token = CancellationToken::new(); + let src = SdJournal::new(&Config::default(), token.clone()); + let Ok((_rx, handle)) = src.spawn_follow(&JournalQuery::default()).await else { + return; + }; + token.cancel(); + tokio::time::timeout(Duration::from_millis(1500), handle) + .await + .expect("follow thread did not exit") + .unwrap(); } }