WS-B: journald source (query, follow, example)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YShymaPrXmc3KYRUg2HMSs
This commit is contained in:
1 parent
2687ef5c33
commit
b1bf04d4ec
4 files changed
+325
-22
No files matched your search
@@ -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
|
- [ ] **A7** Unit tests for timestamp conversion and property mapping
|
||||||
|
|
||||||
### WS-B journal · [card](plan/workstreams/WS-B-journal.md)
|
### WS-B journal · [card](plan/workstreams/WS-B-journal.md)
|
||||||
- [ ] **B1** All sd-journal access inside `spawn_blocking`. Optional namespace, depending on the spike.
|
- [x] **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
|
- [x] **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.
|
- [x] **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`
|
- [x] **B4** Entry mapping with lossy UTF-8 for binary `MESSAGE`
|
||||||
- [ ] **B5** `examples/journal_tail.rs`
|
- [x] **B5** `examples/journal_tail.rs`
|
||||||
- [ ] **B6** Test: the follow thread exits after its receiver is dropped
|
- [x] **B6** Test: the follow thread exits after its receiver is dropped
|
||||||
|
|
||||||
### WS-C docker · [card](plan/workstreams/WS-C-docker.md)
|
### 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`.
|
- [ ] **C1** Lazy `bollard::Docker` on the configured socket. Missing or denied socket maps to `Unavailable`.
|
||||||
|
|||||||
@@ -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::<Priority>() {
|
||||||
|
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);
|
||||||
|
}
|
||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
| Field | Value |
|
| Field | Value |
|
||||||
|---|---|
|
|---|---|
|
||||||
| Status | Backlog |
|
| Status | Review |
|
||||||
| Owner | — |
|
| Owner | — |
|
||||||
| Phase | 1 (parallel) |
|
| Phase | 1 (parallel) |
|
||||||
| Depends on | P0 (incl. spike findings on the `systemd` crate) |
|
| Depends on | P0 (incl. spike findings on the `systemd` crate) |
|
||||||
@@ -45,3 +45,4 @@ Tick these in [`TODO.md`](../../TODO.md).
|
|||||||
## Log
|
## Log
|
||||||
|
|
||||||
- 2026-10-15: Card created.
|
- 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.
|
||||||
+262
-15
@@ -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!()`.
|
//! `systemd::journal::Journal` is neither `Send` nor `Sync`, so every
|
||||||
//! Notes for WS-B: `systemd::journal::Journal` is neither `Send` nor `Sync`.
|
//! sd-journal call happens inside a `spawn_blocking` closure that opens its own
|
||||||
//! Open it inside `spawn_blocking` and never move it across threads or hold it
|
//! handle and drops it before returning. Nothing is held across an `.await`.
|
||||||
//! across an `.await`. Namespaces need `OpenOptions::open_namespace`
|
//!
|
||||||
//! (feature `systemd_v245`, already enabled).
|
//! 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 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 tokio_util::sync::CancellationToken;
|
||||||
|
|
||||||
use super::{JournalEntry, JournalQuery, JournalSource};
|
use super::{clamp_count, JournalEntry, JournalQuery, JournalSource, Priority};
|
||||||
use crate::config::Config;
|
use crate::config::Config;
|
||||||
use crate::error::AppError;
|
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<String>,
|
||||||
|
max_lines: usize,
|
||||||
|
shutdown: CancellationToken,
|
||||||
|
}
|
||||||
|
|
||||||
impl SdJournal {
|
impl SdJournal {
|
||||||
/// Must not fail or block. Reads `sources.journal_namespace` and
|
/// Must not fail or block. Reads `sources.journal_namespace` and
|
||||||
/// `limits.max_lines` from `config`. Follow tasks stop on `shutdown`.
|
/// `limits.max_lines` from `config`. Follow tasks stop on `shutdown`.
|
||||||
pub fn new(_config: &Config, _shutdown: CancellationToken) -> Self {
|
pub fn new(config: &Config, shutdown: CancellationToken) -> Self {
|
||||||
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<JournalEntry>, 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<Journal, AppError> {
|
||||||
|
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::<u8>().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<Vec<JournalEntry>, 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<JournalEntry>, 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<JournalEntry>,
|
||||||
|
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]
|
#[async_trait]
|
||||||
impl JournalSource for SdJournal {
|
impl JournalSource for SdJournal {
|
||||||
async fn query(&self, _q: &JournalQuery) -> Result<Vec<JournalEntry>, AppError> {
|
async fn query(&self, q: &JournalQuery) -> Result<Vec<JournalEntry>, AppError> {
|
||||||
todo!("WS-B B2")
|
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<mpsc::Receiver<JournalEntry>, AppError> {
|
async fn follow(&self, q: &JournalQuery) -> Result<mpsc::Receiver<JournalEntry>, AppError> {
|
||||||
todo!("WS-B B3")
|
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();
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
Reference in new issue
Block a user