sdjournal

sdjournal is a pure Rust systemd journal reader and query engine. It reads *.journal files directly and does not depend on libsystemd or invoke journalctl (tests may use journalctl for golden comparisons).

Overview

• Pure Rust, with no libsystemd dependency
• Bounded, corruption-resistant parsing for production use
• Stable merge ordering, cursor checkpoints, and follow/tail support
• Optional mmap, compression backends, tracing, Tokio follow, and FSS verification

Compatibility

• Target OS: Linux
• Non-Linux builds compile, but Journal::open_default() is Linux-only
• CI coverage includes Ubuntu 22.04 (systemd 249.x) and Ubuntu 24.04 (systemd 255.x)

Install

cargo add sdjournal

Features

• Default: mmap, lz4, zstd
• Optional:
  • xz: enable XZ decompression
  • tracing: emit diagnostics via tracing (caller installs a subscriber)
  • tokio: provides an async follow adapter
  • verify-seal: verify Forward Secure Sealing (TAG/FSS) with a systemd verification key

Quickstart

use sdjournal::Journal;

let journal = Journal::open_default()?;
let mut q = journal.query();
q.match_exact("_SYSTEMD_UNIT", b"sshd.service");
q.since_realtime(0);

for item in q.iter()? {
    let entry = item?;
    if let Some(msg) = entry.get("MESSAGE") {
        println!("{}", String::from_utf8_lossy(msg));
    }
}
# Ok::<(), sdjournal::SdJournalError>(())

Resume From Cursor

An end-to-end example that persists the last cursor and resumes via after_cursor is in:

• examples/checkpoint_follow.rs

Run it on Linux:

cargo run --example checkpoint_follow -- sshd.service /var/tmp/sdjournal.cursor

Start Here

To understand the crate quickly, read or run these examples in order:

• tour: guided walkthrough of Journal, JournalQuery, EntryRef/EntryOwned, Cursor, and Follow
• tail: the smallest “open default journal and read entries” path
• match_unit: the most common production filter shape
• checkpoint_follow: resume-safe follow loop for long-running consumers

Examples

Open / discovery:

• tour: guided API overview and mental model
• open_dir: open one journal directory and print entries
• open_dirs: merge multiple journal roots
• open_with_config: customize JournalConfig

Query builder patterns:

• tail: print the newest entries from the default journal
• filter_exact: query by an exact field/value pair
• match_present: query by field presence
• match_unit: query one systemd unit
• or_units: OR across two units with or_group
• recent_unit: query a unit within a recent time window
• print_fields: dump all fields from the newest matching entry
• collect_owned: detach results into EntryOwned

Cursor / resume:

• cursor_roundtrip: print a cursor and resume from it with seek_cursor
• after_cursor: resume strictly after a saved cursor string
• checkpoint_follow: persist cursors while following

Streaming / integration:

• follow_unit: block and print a few newly appended entries
• follow_tokio: use the Tokio follow adapter (--features tokio)
• verify_seal: verify FSS tags (--features verify-seal)