diff --git a/komorebi-recorder/src/platform/linux/mod.rs b/komorebi-recorder/src/platform/linux/mod.rs index 29bf7d20..57989743 100644 --- a/komorebi-recorder/src/platform/linux/mod.rs +++ b/komorebi-recorder/src/platform/linux/mod.rs @@ -1,13 +1,9 @@ //! Linux, as KDE Plasma: the host that records komorebi for KDE. //! -//! The master clock, the child processes, the shell, the screen capture, power, the session lock -//! and the window list are Linux's own. The OS trace is still the `unsupported` host's, and is -//! replaced when it is written (see `docs/PLATFORM.md`). - -// the pieces of the fallback that Linux has its own version of are not used -#[allow(dead_code)] -#[path = "../unsupported.rs"] -mod fallback; +//! The master clock is `CLOCK_MONOTONIC`; the screen is the compositor's screencast, read through +//! PipeWire and written by GStreamer; sleep and the lock are heard on D-Bus; the windows are +//! komorebi for KDE's own; and the OS trace is the journal. What each does, and what it cannot, +//! is in `docs/PLATFORM.md`. pub mod apps; pub mod capture; @@ -17,9 +13,8 @@ pub mod process; mod screencast; pub mod session; pub mod shell; +pub mod trace; pub mod wayland; -pub use fallback::trace; - /// Nothing to do first. pub fn init() {} diff --git a/komorebi-recorder/src/platform/linux/trace.rs b/komorebi-recorder/src/platform/linux/trace.rs new file mode 100644 index 00000000..71316719 --- /dev/null +++ b/komorebi-recorder/src/platform/linux/trace.rs @@ -0,0 +1,215 @@ +//! The OS trace on Linux: the journal, as it is written. +//! +//! The compositor and the shell log to the journal, and so do the things that go wrong around a +//! window manager (a GPU that resets, a PipeWire that restarts, the portal). Two `journalctl` +//! children follow it from now on, as `-o json`, and each entry becomes a record of the same shape +//! as the Mac's unified log and the Windows trace ([`TraceRecord`]): +//! +//! | stream | what it follows | in the manifest | +//! |---|---|---| +//! | `system` | the user's journal, of the programs that put windows on the screen: `kwin_wayland`, `plasmashell`, `komorebi` | `journal` | +//! | `event_log` | every priority of warning and worse, from the system journal and the user's | `journal-warnings` | +//! +//! The time of an entry is `__MONOTONIC_TIMESTAMP`, which is the clock the master clock reads +//! (`CLOCK_MONOTONIC`) when the entry was written, so it is on the master clock as it is. A user +//! who may not read the system journal (not in `systemd-journal`) has the user's only, and the +//! reason is in the problems. +//! +//! The children end when the taps are dropped. + +use crate::platform::process; +use crate::sources::wintrace::TraceRecord; +use crate::sources::wintrace::TraceStream; +use serde_json::Value; +use std::io::BufRead; +use std::io::BufReader; +use std::process::Child; +use std::process::Command; +use std::process::Stdio; +use std::sync::Arc; +use std::thread::JoinHandle; + +/// What the manifest calls the stream of the programs that put windows on the screen. +pub const SYSTEM_NAME: &str = "journal"; +/// What the manifest calls the stream of warnings. +pub const EVENT_LOG_NAME: &str = "journal-warnings"; +/// What the first stream is, for the manifest. +pub const SYSTEM_ABOUT: &str = "journalctl --user -f: kwin_wayland, plasmashell and komorebi"; +/// What the second stream is, for the manifest. +pub const EVENT_LOG_ABOUT: &str = "journalctl -f -p warning: the system's warnings and errors"; + +/// The running taps, which listen until dropped. +pub struct Taps { + children: Vec, + readers: Vec>, +} + +impl Drop for Taps { + fn drop(&mut self) { + for child in &mut self.children { + process::terminate(child); + } + for child in &mut self.children { + let _ = child.wait(); + } + // the pipes are closed with the children, which ends each reader + for reader in self.readers.drain(..) { + let _ = reader.join(); + } + } +} + +/// How a journal priority is named in a record: the names the Mac's records use. +fn level_of(priority: &str) -> &'static str { + match priority { + "0" | "1" | "2" => "Fault", + "3" => "Error", + "7" => "Debug", + _ => "Info", + } +} + +fn text<'a>(entry: &'a Value, key: &str) -> Option<&'a str> { + entry.get(key).and_then(Value::as_str) +} + +/// Returns the record that one line of `journalctl -o json` is, or `None` for a line that is not +/// an entry, or has no time on the master clock, or has a message that is not text. +/// +#[must_use] +pub fn record_of(line: &str) -> Option { + let entry: Value = serde_json::from_str(line).ok()?; + let host_us: u64 = text(&entry, "__MONOTONIC_TIMESTAMP")?.parse().ok()?; + let wall_us: i64 = text(&entry, "__REALTIME_TIMESTAMP")?.parse().ok()?; + // a message that is not text (a binary one) is an array of bytes, which says nothing here + let message = text(&entry, "MESSAGE")?.to_string(); + let process = text(&entry, "_COMM") + .or_else(|| text(&entry, "SYSLOG_IDENTIFIER")) + .unwrap_or_default(); + Some(TraceRecord { + host_ns: host_us.saturating_mul(1000), + wall_us, + pid: text(&entry, "_PID") + .and_then(|pid| pid.parse().ok()) + .unwrap_or(0), + process: process.to_string(), + subsystem: "journal".to_string(), + category: text(&entry, "SYSLOG_IDENTIFIER") + .or_else(|| text(&entry, "_SYSTEMD_UNIT")) + .unwrap_or_default() + .to_string(), + level: level_of(text(&entry, "PRIORITY").unwrap_or("6")), + message, + }) +} + +/// Follows the journal with `arguments`, writing each entry to `stream`. +fn follow(arguments: &[&str], stream: Arc) -> Result<(Child, JoinHandle<()>), String> { + let mut command = Command::new("journalctl"); + command + .args(["-f", "-n", "0", "-o", "json", "--no-pager"]) + .args(arguments) + .stdin(Stdio::null()) + .stdout(Stdio::piped()) + .stderr(Stdio::null()); + let mut child = process::isolate(&mut command) + .spawn() + .map_err(|error| format!("could not run journalctl: {error}"))?; + let stdout = child + .stdout + .take() + .ok_or_else(|| "journalctl has no output".to_string())?; + let reader = std::thread::Builder::new() + .name("komorebi-recorder-journal".to_string()) + .spawn(move || { + for line in BufReader::new(stdout).lines().map_while(Result::ok) { + if let Some(record) = record_of(&line) { + stream.write(&record); + } + } + }) + .map_err(|error| format!("could not start the reader: {error}"))?; + Ok((child, reader)) +} + +/// Starts following the journal, into `system` and `event_log`. +/// +/// Returns the taps, or `None` if neither could start, and why each that could not start could +/// not, in words that begin with the stream's name; the recording goes on without it. +#[must_use] +pub fn start(system: Arc, event_log: Arc) -> (Option, Vec) { + let mut taps = Taps { + children: Vec::new(), + readers: Vec::new(), + }; + let mut problems = Vec::new(); + + let wanted = [ + ( + SYSTEM_NAME, + system, + &[ + "--user", + "_COMM=kwin_wayland", + "+", + "_COMM=plasmashell", + "+", + "_COMM=komorebi", + ][..], + ), + (EVENT_LOG_NAME, event_log, &["-p", "warning"][..]), + ]; + for (name, stream, arguments) in wanted { + match follow(arguments, stream) { + Ok((child, reader)) => { + taps.children.push(child); + taps.readers.push(reader); + } + Err(why) => problems.push(format!("{name}: {why}")), + } + } + + ((!taps.children.is_empty()).then_some(taps), problems) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn an_entry_is_a_record_on_the_master_clock() { + let line = r#"{"__MONOTONIC_TIMESTAMP":"5000000","__REALTIME_TIMESTAMP":"1793016000123456","_PID":"812","_COMM":"kwin_wayland","SYSLOG_IDENTIFIER":"kwin_wayland","PRIORITY":"4","MESSAGE":"Atom 0 not found"}"#; + let record = record_of(line).expect("an entry"); + assert_eq!(record.host_ns, 5_000_000_000); + assert_eq!((record.pid, record.process.as_str()), (812, "kwin_wayland")); + assert_eq!(record.level, "Info"); + assert_eq!(record.message, "Atom 0 not found"); + assert!(record_of("not json").is_none()); + } + + #[test] + fn priorities_are_named_as_the_macs_records_are() { + assert_eq!(level_of("0"), "Fault"); + assert_eq!(level_of("3"), "Error"); + assert_eq!(level_of("4"), "Info"); + assert_eq!(level_of("6"), "Info"); + assert_eq!(level_of("7"), "Debug"); + } + + #[test] + fn an_entry_with_a_binary_message_is_left_out() { + let line = + r#"{"__MONOTONIC_TIMESTAMP":"1","__REALTIME_TIMESTAMP":"2","MESSAGE":[104,105]}"#; + assert!(record_of(line).is_none()); + } + + #[test] + fn an_entry_without_a_process_is_named_by_its_identifier() { + let line = r#"{"__MONOTONIC_TIMESTAMP":"1000","__REALTIME_TIMESTAMP":"2","SYSLOG_IDENTIFIER":"pipewire","MESSAGE":"restarted"}"#; + let record = record_of(line).expect("an entry"); + assert_eq!(record.process, "pipewire"); + assert_eq!(record.category, "pipewire"); + assert_eq!(record.pid, 0); + assert_eq!(record.host_ns, 1_000_000); + } +} diff --git a/komorebi-recorder/src/platform/macos/trace.rs b/komorebi-recorder/src/platform/macos/trace.rs index 098edbf9..787cc635 100644 --- a/komorebi-recorder/src/platform/macos/trace.rs +++ b/komorebi-recorder/src/platform/macos/trace.rs @@ -8,6 +8,15 @@ use crate::sources::wintrace::TraceStream; use std::sync::Arc; +/// What the manifest calls the first stream, on a host that has one. +pub const SYSTEM_NAME: &str = "winevents"; +/// What the manifest calls the second stream, on a host that has one. +pub const EVENT_LOG_NAME: &str = "eventlog"; +/// What the first stream is, for the manifest. +pub const SYSTEM_ABOUT: &str = ""; +/// What the second stream is, for the manifest. +pub const EVENT_LOG_ABOUT: &str = ""; + /// The running taps, which listen until dropped. Never constructed on this host: [`start`] /// returns none. pub struct Taps; diff --git a/komorebi-recorder/src/platform/mod.rs b/komorebi-recorder/src/platform/mod.rs index 2f33da9e..eb9f98d7 100644 --- a/komorebi-recorder/src/platform/mod.rs +++ b/komorebi-recorder/src/platform/mod.rs @@ -73,7 +73,7 @@ pub mod window; /// That is the unified log on macOS, and the `WinEvents` komorebi hears and the Event Log on /// Windows. A recording made on a host with none says so rather than failing to start streams that /// do not exist. -pub const HAS_OS_TRACE: bool = cfg!(any(target_os = "macos", windows)); +pub const HAS_OS_TRACE: bool = cfg!(any(target_os = "macos", windows, target_os = "linux")); /// Things the OS wants done once, first thing in `main`: on Windows, becoming DPI aware so that /// sizes and positions are in physical pixels. Nothing on other hosts. diff --git a/komorebi-recorder/src/platform/unsupported.rs b/komorebi-recorder/src/platform/unsupported.rs index 43546f6d..e3fa767b 100644 --- a/komorebi-recorder/src/platform/unsupported.rs +++ b/komorebi-recorder/src/platform/unsupported.rs @@ -170,6 +170,15 @@ pub mod trace { use crate::sources::wintrace::TraceStream; use std::sync::Arc; + /// What the manifest calls the first stream, on a host that has one. + pub const SYSTEM_NAME: &str = "winevents"; + /// What the manifest calls the second stream, on a host that has one. + pub const EVENT_LOG_NAME: &str = "eventlog"; + /// What the first stream is, for the manifest. + pub const SYSTEM_ABOUT: &str = ""; + /// What the second stream is, for the manifest. + pub const EVENT_LOG_ABOUT: &str = ""; + /// Never constructed on this host. pub struct Taps; diff --git a/komorebi-recorder/src/platform/win/trace.rs b/komorebi-recorder/src/platform/win/trace.rs index 8b0eb4b6..2f30c289 100644 --- a/komorebi-recorder/src/platform/win/trace.rs +++ b/komorebi-recorder/src/platform/win/trace.rs @@ -18,6 +18,15 @@ //! reading it uses are tested in [`crate::sources::wintrace`], and the taps are checked on a real //! machine (see `docs/dev/windows-checkpoints.md`). +/// What the manifest calls the stream of `WinEvent`s. +pub const SYSTEM_NAME: &str = "winevents"; +/// What the manifest calls the stream of the Event Log. +pub const EVENT_LOG_NAME: &str = "eventlog"; +/// What the stream of `WinEvent`s is, for the manifest. +pub const SYSTEM_ABOUT: &str = "WinEvent hook on every top-level window"; +/// What the stream of the Event Log is, for the manifest. +pub const EVENT_LOG_ABOUT: &str = "System Event Log: warnings, errors, display and power providers"; + use crate::clock; use crate::sources::wintrace::Coalescer; use crate::sources::wintrace::Offer; diff --git a/komorebi-recorder/src/sources/wintrace.rs b/komorebi-recorder/src/sources/wintrace.rs index dd1df677..ad7e05de 100644 --- a/komorebi-recorder/src/sources/wintrace.rs +++ b/komorebi-recorder/src/sources/wintrace.rs @@ -625,8 +625,18 @@ impl TraceSet { /// Returns an error if either file cannot be created (see [`TraceStream::create`]). A tap that /// fails to start is not an error. pub fn start(dir: &Path) -> eyre::Result { - let system = TraceStream::create(dir, "winevents", "oslog:system", SYSTEM_FILE)?; - let event_log = TraceStream::create(dir, "eventlog", "oslog:eventlog", EVENT_LOG_FILE)?; + let system = TraceStream::create( + dir, + crate::platform::trace::SYSTEM_NAME, + "oslog:system", + SYSTEM_FILE, + )?; + let event_log = TraceStream::create( + dir, + crate::platform::trace::EVENT_LOG_NAME, + "oslog:eventlog", + EVENT_LOG_FILE, + )?; let (taps, problems) = crate::platform::trace::start(system.clone(), event_log.clone()); Ok(Self { @@ -659,12 +669,12 @@ impl TraceSet { }; vec![ self.system.info( - "WinEvent hook on every top-level window", - error("winevents"), + crate::platform::trace::SYSTEM_ABOUT, + error(crate::platform::trace::SYSTEM_NAME), ), self.event_log.info( - "System Event Log: warnings, errors, display and power providers", - error("eventlog"), + crate::platform::trace::EVENT_LOG_ABOUT, + error(crate::platform::trace::EVENT_LOG_NAME), ), ] }