diff --git a/Cargo.lock b/Cargo.lock index 6a2abfd5..5e02d921 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -469,6 +469,7 @@ dependencies = [ "libc", "objc2-core-foundation", "objc2-core-graphics", + "parking_lot", "schemars", "serde", "serde_json_lenient", @@ -509,6 +510,15 @@ version = "0.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53" +[[package]] +name = "lock_api" +version = "0.4.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965" +dependencies = [ + "scopeguard", +] + [[package]] name = "log" version = "0.4.29" @@ -601,6 +611,29 @@ version = "4.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d211803b9b6b570f68772237e415a029d5a50c65d382910b879fb19d3271f94d" +[[package]] +name = "parking_lot" +version = "0.12.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a" +dependencies = [ + "lock_api", + "parking_lot_core", +] + +[[package]] +name = "parking_lot_core" +version = "0.9.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1" +dependencies = [ + "cfg-if", + "libc", + "redox_syscall", + "smallvec", + "windows-link", +] + [[package]] name = "pin-project-lite" version = "0.2.17" @@ -641,6 +674,15 @@ version = "6.0.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" +[[package]] +name = "redox_syscall" +version = "0.5.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d" +dependencies = [ + "bitflags", +] + [[package]] name = "redox_users" version = "0.5.2" @@ -728,6 +770,12 @@ dependencies = [ "syn", ] +[[package]] +name = "scopeguard" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" + [[package]] name = "semver" version = "1.0.28" @@ -821,6 +869,12 @@ version = "0.4.12" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" +[[package]] +name = "smallvec" +version = "1.15.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03" + [[package]] name = "strsim" version = "0.11.1" diff --git a/dependencies.json b/dependencies.json index d95fe1eb..bd3be8f8 100644 --- a/dependencies.json +++ b/dependencies.json @@ -46,6 +46,7 @@ "itoa 1.0.18 registry+https://github.com/rust-lang/crates.io-index", "lazy_static 1.5.0 registry+https://github.com/rust-lang/crates.io-index", "libc 0.2.186 registry+https://github.com/rust-lang/crates.io-index", + "lock_api 0.4.14 registry+https://github.com/rust-lang/crates.io-index", "miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index", "num-traits 0.2.19 registry+https://github.com/rust-lang/crates.io-index", "objc2-core-foundation 0.3.2 registry+https://github.com/rust-lang/crates.io-index", @@ -53,6 +54,8 @@ "object 0.37.3 registry+https://github.com/rust-lang/crates.io-index", "once_cell 1.21.4 registry+https://github.com/rust-lang/crates.io-index", "once_cell_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index", + "parking_lot 0.12.5 registry+https://github.com/rust-lang/crates.io-index", + "parking_lot_core 0.9.12 registry+https://github.com/rust-lang/crates.io-index", "pin-project-lite 0.2.17 registry+https://github.com/rust-lang/crates.io-index", "proc-macro2 1.0.106 registry+https://github.com/rust-lang/crates.io-index", "quote 1.0.45 registry+https://github.com/rust-lang/crates.io-index", @@ -61,12 +64,14 @@ "rustc-demangle 0.1.27 registry+https://github.com/rust-lang/crates.io-index", "rustix 1.1.4 registry+https://github.com/rust-lang/crates.io-index", "ryu 1.0.23 registry+https://github.com/rust-lang/crates.io-index", + "scopeguard 1.2.0 registry+https://github.com/rust-lang/crates.io-index", "serde 1.0.228 registry+https://github.com/rust-lang/crates.io-index", "serde_core 1.0.228 registry+https://github.com/rust-lang/crates.io-index", "serde_derive 1.0.228 registry+https://github.com/rust-lang/crates.io-index", "serde_derive_internals 0.29.1 registry+https://github.com/rust-lang/crates.io-index", "serde_json 1.0.149 registry+https://github.com/rust-lang/crates.io-index", "serde_json_lenient 0.2.4 registry+https://github.com/rust-lang/crates.io-index", + "smallvec 1.15.1 registry+https://github.com/rust-lang/crates.io-index", "syn 2.0.117 registry+https://github.com/rust-lang/crates.io-index", "tempfile 3.27.0 registry+https://github.com/rust-lang/crates.io-index", "terminal_size 0.4.4 registry+https://github.com/rust-lang/crates.io-index", @@ -151,6 +156,7 @@ "itoa 1.0.18 registry+https://github.com/rust-lang/crates.io-index", "lazy_static 1.5.0 registry+https://github.com/rust-lang/crates.io-index", "libc 0.2.186 registry+https://github.com/rust-lang/crates.io-index", + "lock_api 0.4.14 registry+https://github.com/rust-lang/crates.io-index", "memchr 2.8.0 registry+https://github.com/rust-lang/crates.io-index", "memoffset 0.9.1 registry+https://github.com/rust-lang/crates.io-index", "miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index", @@ -161,6 +167,8 @@ "once_cell 1.21.4 registry+https://github.com/rust-lang/crates.io-index", "once_cell_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index", "owo-colors 4.3.0 registry+https://github.com/rust-lang/crates.io-index", + "parking_lot 0.12.5 registry+https://github.com/rust-lang/crates.io-index", + "parking_lot_core 0.9.12 registry+https://github.com/rust-lang/crates.io-index", "pin-project-lite 0.2.17 registry+https://github.com/rust-lang/crates.io-index", "proc-macro2 1.0.106 registry+https://github.com/rust-lang/crates.io-index", "quote 1.0.45 registry+https://github.com/rust-lang/crates.io-index", @@ -170,6 +178,7 @@ "rustix 1.1.4 registry+https://github.com/rust-lang/crates.io-index", "schemars 1.2.1 registry+https://github.com/rust-lang/crates.io-index", "schemars_derive 1.2.1 registry+https://github.com/rust-lang/crates.io-index", + "scopeguard 1.2.0 registry+https://github.com/rust-lang/crates.io-index", "serde 1.0.228 registry+https://github.com/rust-lang/crates.io-index", "serde_core 1.0.228 registry+https://github.com/rust-lang/crates.io-index", "serde_derive 1.0.228 registry+https://github.com/rust-lang/crates.io-index", @@ -177,6 +186,7 @@ "serde_json 1.0.149 registry+https://github.com/rust-lang/crates.io-index", "serde_json_lenient 0.2.4 registry+https://github.com/rust-lang/crates.io-index", "sharded-slab 0.1.7 registry+https://github.com/rust-lang/crates.io-index", + "smallvec 1.15.1 registry+https://github.com/rust-lang/crates.io-index", "strsim 0.11.1 registry+https://github.com/rust-lang/crates.io-index", "syn 2.0.117 registry+https://github.com/rust-lang/crates.io-index", "tempfile 3.27.0 registry+https://github.com/rust-lang/crates.io-index", diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 45b48568..b132559a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -74,6 +74,7 @@ build is refused with an error that says so, rather than read wrongly. The files beside it are the raw records, and they are written as the data arrives and never rewritten: komorebi's log (`komorebi.log`, the exact byte range recorded), its events (`events.jsonl`, with full `State` snapshots in `states/` only when they changed), and what happened to the recording itself (`recorder.jsonl`). +The OS trace is under `oslog/`, one file per stream. ## Rules and the layer that enforces them diff --git a/docs/PLATFORM.md b/docs/PLATFORM.md index c9a1dd9e..6d822283 100644 --- a/docs/PLATFORM.md +++ b/docs/PLATFORM.md @@ -46,6 +46,17 @@ Video frame times and the OS trace are on the master clock already on both hosts `machTimestamp` on a Mac; Windows.Graphics.Capture on Windows). The field names ending in `_mach_ns` are spelled that way on every host: see [the architecture](ARCHITECTURE.md#the-master-clock). +### The OS trace + +| | macOS | Windows | +|---|---|---| +| source | the unified log, through `log stream --style ndjson` child processes | WinEvents for every top-level window, through a hook, and the System Event Log | +| files | `oslog/komorebi.ndjson`, `oslog/system.ndjson` and one `oslog/apps/-.ndjson` per managed application | `oslog/system.ndjson` (the WinEvents, repeats folded) and `oslog/eventlog.ndjson` (warnings, errors and the display, power and GPU providers) | +| permissions | none: no `sudo` and no change to SIP | none | +| redaction | `` values stay redacted | not applicable | + +A host with no OS trace says so in the recording instead of failing to start streams that do not exist. + ### Locking a session A recording holds an exclusive lock on `recorder.lock` in its session for as long as it runs, and writes its process id diff --git a/komorebi-recorder/Cargo.toml b/komorebi-recorder/Cargo.toml index 9373c315..a2698bbf 100644 --- a/komorebi-recorder/Cargo.toml +++ b/komorebi-recorder/Cargo.toml @@ -11,6 +11,7 @@ clap = { workspace = true } color-eyre = { workspace = true } crossbeam-channel = { workspace = true } dirs = { workspace = true } +parking_lot = { workspace = true } schemars = { workspace = true } serde = { workspace = true } serde_json = { workspace = true } diff --git a/komorebi-recorder/src/platform/macos/mod.rs b/komorebi-recorder/src/platform/macos/mod.rs index cc43b9cc..eb24c48b 100644 --- a/komorebi-recorder/src/platform/macos/mod.rs +++ b/komorebi-recorder/src/platform/macos/mod.rs @@ -18,6 +18,7 @@ pub mod apps; pub mod clock; pub mod process; pub mod shell; +pub mod trace; /// Does nothing: a Mac needs nothing done once at the start of `main`. (Windows makes the process /// DPI aware.) diff --git a/komorebi-recorder/src/platform/macos/trace.rs b/komorebi-recorder/src/platform/macos/trace.rs new file mode 100644 index 00000000..098edbf9 --- /dev/null +++ b/komorebi-recorder/src/platform/macos/trace.rs @@ -0,0 +1,30 @@ +//! The OS-trace taps: none on macOS. +//! +//! macOS records its OS trace with `log stream` children (see [`crate::sources::oslog`]), not with +//! taps of its own, so there is nothing to start here and [`start`] starts none. On Windows the +//! taps are a `WinEvent` hook and Event Log subscriptions, which feed the two files of +//! [`crate::sources::wintrace`]. + +use crate::sources::wintrace::TraceStream; +use std::sync::Arc; + +/// The running taps, which listen until dropped. Never constructed on this host: [`start`] +/// returns none. +pub struct Taps; + +/// Starts the OS-trace taps, writing into `system` and `event_log`. This host starts none and +/// returns `None` with one problem in words, saying that the OS trace is recorded another way. +/// +/// The second element of the result lists why a tap could not be started, one entry each; the +/// recording goes on without it. On Windows the taps are always returned, with an entry for each +/// that failed. +#[must_use] +pub fn start( + _system: Arc, + _event_log: Arc, +) -> (Option, Vec) { + ( + None, + vec!["winevents: this host records its OS trace another way".to_string()], + ) +} diff --git a/komorebi-recorder/src/platform/mod.rs b/komorebi-recorder/src/platform/mod.rs index ed39d858..852352cf 100644 --- a/komorebi-recorder/src/platform/mod.rs +++ b/komorebi-recorder/src/platform/mod.rs @@ -9,6 +9,7 @@ //! | [`shell`] | the OS version, and (for the recorder window) showing a folder and asking for one | //! | [`apps`] | which process owns a window id | //! | [`process`] | stopping a child process | +//! | [`trace`] | streaming the OS trace into the session | //! //! A third host, `unsupported`, builds on anything else so that the investigation commands (which //! only read a session directory) still work on a Linux agent box; recording there says so. @@ -48,6 +49,14 @@ pub use imp::apps; pub use imp::clock; pub use imp::process; pub use imp::shell; +pub use imp::trace; + +/// Whether this host has an OS trace to record alongside komorebi's own output. +/// +/// 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)); /// 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 b23f88f5..d9a0c064 100644 --- a/komorebi-recorder/src/platform/unsupported.rs +++ b/komorebi-recorder/src/platform/unsupported.rs @@ -47,6 +47,27 @@ pub mod clock { } } +/// The OS trace, which this host does not have. +pub mod trace { + use crate::sources::wintrace::TraceStream; + use std::sync::Arc; + + /// Never constructed on this host. + pub struct Taps; + + /// Returns no taps and the reason: this host has no OS trace. + #[must_use] + pub fn start( + _system: Arc, + _event_log: Arc, + ) -> (Option, Vec) { + ( + None, + vec!["winevents: this host has no OS trace".to_string()], + ) + } +} + /// Starting and stopping child processes, with nothing host-specific to do. pub mod process { use std::process::Child; diff --git a/komorebi-recorder/src/platform/win/mod.rs b/komorebi-recorder/src/platform/win/mod.rs index 1c946bfe..c0287a83 100644 --- a/komorebi-recorder/src/platform/win/mod.rs +++ b/komorebi-recorder/src/platform/win/mod.rs @@ -25,6 +25,7 @@ pub mod apps; pub mod clock; pub mod process; pub mod shell; +pub mod trace; /// Does what Windows needs once, first thing in `main`: makes the process per-monitor DPI aware /// ([`capture::become_per_monitor_dpi_aware`]), so that every size and position it reads is in diff --git a/komorebi-recorder/src/platform/win/trace.rs b/komorebi-recorder/src/platform/win/trace.rs new file mode 100644 index 00000000..8b0eb4b6 --- /dev/null +++ b/komorebi-recorder/src/platform/win/trace.rs @@ -0,0 +1,441 @@ +//! The two taps of the Windows OS trace: a `WinEvent` hook, and Event Log subscriptions. See +//! [`crate::sources::wintrace`] for what is recorded and why. +//! +//! [`start`] starts both and returns them as one [`Taps`], which listens until it is dropped: +//! +//! - **The `WinEvent` hook** runs on a thread of its own (`komorebi-recorder-winevents`): it +//! installs `SetWinEventHook` for every event of every process except the recorder's own, and +//! pumps messages because the hook is delivered through them. The hook callback only stamps the +//! event on the master clock and the wall clock and queues it. A second thread +//! (`komorebi-recorder-trace-sink`) folds bursts ([`Coalescer`]), looks up the window's class and +//! program, and writes the record to the `system` stream. +//! - **The Event Log subscriptions** are two `EvtSubscribe` queries on the `System` channel for +//! future events, delivered on threads of the system's. Each event is rendered to XML, +//! summarized ([`summarize_event_xml`]) and written to the `event_log` stream. +//! +//! macOS has no taps: [`crate::platform::trace`] there starts none and its OS trace is `log +//! stream`. Nothing tests this module automatically: the record format, the folding and the XML +//! reading it uses are tested in [`crate::sources::wintrace`], and the taps are checked on a real +//! machine (see `docs/dev/windows-checkpoints.md`). + +use crate::clock; +use crate::sources::wintrace::Coalescer; +use crate::sources::wintrace::Offer; +use crate::sources::wintrace::TraceRecord; +use crate::sources::wintrace::TraceStream; +use crate::sources::wintrace::is_noisy; +use crate::sources::wintrace::summarize_event_xml; +use crate::sources::wintrace::win_event_name; +use crossbeam_channel::Receiver; +use crossbeam_channel::Sender; +use parking_lot::Mutex; +use std::collections::HashMap; +use std::ffi::c_void; +use std::sync::Arc; +use std::sync::OnceLock; +use std::thread::JoinHandle; +use windows::Win32::Foundation::HWND; +use windows::Win32::Foundation::LPARAM; +use windows::Win32::Foundation::WPARAM; +use windows::Win32::System::EventLog::EVT_HANDLE; +use windows::Win32::System::EventLog::EVT_SUBSCRIBE_NOTIFY_ACTION; +use windows::Win32::System::EventLog::EvtClose; +use windows::Win32::System::EventLog::EvtRender; +use windows::Win32::System::EventLog::EvtRenderEventXml; +use windows::Win32::System::EventLog::EvtSubscribe; +use windows::Win32::System::EventLog::EvtSubscribeActionDeliver; +use windows::Win32::System::EventLog::EvtSubscribeToFutureEvents; +use windows::Win32::System::Threading::GetCurrentThreadId; +use windows::Win32::UI::Accessibility::HWINEVENTHOOK; +use windows::Win32::UI::Accessibility::SetWinEventHook; +use windows::Win32::UI::Accessibility::UnhookWinEvent; +use windows::Win32::UI::WindowsAndMessaging::CHILDID_SELF; +use windows::Win32::UI::WindowsAndMessaging::DispatchMessageW; +use windows::Win32::UI::WindowsAndMessaging::EVENT_MAX; +use windows::Win32::UI::WindowsAndMessaging::EVENT_MIN; +use windows::Win32::UI::WindowsAndMessaging::GA_ROOT; +use windows::Win32::UI::WindowsAndMessaging::GetAncestor; +use windows::Win32::UI::WindowsAndMessaging::GetClassNameW; +use windows::Win32::UI::WindowsAndMessaging::GetMessageW; +use windows::Win32::UI::WindowsAndMessaging::GetWindowThreadProcessId; +use windows::Win32::UI::WindowsAndMessaging::MSG; +use windows::Win32::UI::WindowsAndMessaging::OBJID_WINDOW; +use windows::Win32::UI::WindowsAndMessaging::PostThreadMessageW; +use windows::Win32::UI::WindowsAndMessaging::TranslateMessage; +use windows::Win32::UI::WindowsAndMessaging::WINEVENT_OUTOFCONTEXT; +use windows::Win32::UI::WindowsAndMessaging::WINEVENT_SKIPOWNPROCESS; +use windows::Win32::UI::WindowsAndMessaging::WM_QUIT; +use windows::core::HSTRING; + +/// An event as the hook heard it: the least that can be done on the hook's thread. +struct Heard { + host_ns: u64, + wall_us: i64, + event: u32, + window: isize, +} + +/// The hook has no user data, so what it feeds is here. +static HEARD: OnceLock>>> = OnceLock::new(); + +unsafe extern "system" fn on_win_event( + _hook: HWINEVENTHOOK, + event: u32, + window: HWND, + id_object: i32, + id_child: i32, + _thread: u32, + _time: u32, +) { + // only windows themselves, not the objects inside them + if id_object != OBJID_WINDOW.0 || id_child != CHILDID_SELF as i32 || window.0.is_null() { + return; + } + + if let Some(sender) = HEARD.get().and_then(|heard| heard.lock().clone()) { + let _ = sender.send(Heard { + host_ns: clock::mono_now_ns(), + wall_us: clock::wall_now_us(), + event, + window: window.0 as isize, + }); + } +} + +/// Everything about a window that is cheap to ask and may already be gone: its class and owner. +fn describe(window: isize) -> Option<(i64, String, String)> { + let hwnd = HWND(window as *mut c_void); + + // a child window is a part of one; the events worth keeping are the top-level windows'. A + // window already destroyed has no ancestor to ask about, and a destroy is worth keeping. + // SAFETY: queries about a handle that may be stale, which they report as a failure + let root = unsafe { GetAncestor(hwnd, GA_ROOT) }; + if !root.0.is_null() && root != hwnd { + return None; + } + + let mut pid = 0_u32; + // SAFETY: as above, with a valid out pointer + unsafe { GetWindowThreadProcessId(hwnd, Some(&raw mut pid)) }; + + let mut class = [0_u16; 128]; + // SAFETY: the buffer is valid for its length + let length = unsafe { GetClassNameW(hwnd, &mut class) }; + let class = String::from_utf16_lossy(&class[..usize::try_from(length).unwrap_or(0)]); + + let process = if pid == 0 { + String::new() + } else { + super::apps::process_name(pid).map_or_else(String::new, |name| format!("{name}.exe")) + }; + + Some((i64::from(pid), process, class)) +} + +/// Turns what the hook heard into records. +fn sink(heard: &Receiver, stream: &TraceStream) { + let mut coalescer = Coalescer::default(); + // a process's name is asked for once per program: pids come and go but the cache is cleared + // before it can grow without bound + let mut names: HashMap = HashMap::new(); + + while let Ok(event) = heard.recv() { + let folded = match coalescer.offer(event.host_ns, event.window, event.event) { + Offer::Fold => continue, + Offer::Emit { folded } => folded, + }; + + let Some((pid, process, class)) = describe(event.window) else { + continue; + }; + if names.len() > 1024 { + names.clear(); + } + let process = if process.is_empty() { + names.get(&pid).cloned().unwrap_or_default() + } else { + names.insert(pid, process.clone()); + process + }; + + let name = win_event_name(event.event); + stream.write(&TraceRecord { + host_ns: event.host_ns, + wall_us: event.wall_us, + pid, + process, + subsystem: "winevent".to_string(), + level: if is_noisy(event.event) { + "Debug" + } else { + "Info" + }, + message: format!( + "{name} hwnd=0x{:x} class={class}{}", + event.window, + if folded > 0 { + format!(" (+{folded} like it folded in)") + } else { + String::new() + } + ), + category: name, + }); + } +} + +/// The hook's thread: install it, then pump messages (it is delivered through them) until told to +/// stop. +fn hook_thread(ready: &std::sync::mpsc::Sender>) { + // SAFETY: installing a hook that calls `on_win_event`, which does nothing unsafe; the hook is + // removed below before the thread ends + let hook = unsafe { + SetWinEventHook( + EVENT_MIN, + EVENT_MAX, + None, + Some(on_win_event), + 0, + 0, + WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS, + ) + }; + if hook.0.is_null() { + let _ = ready.send(Err("SetWinEventHook failed".to_string())); + return; + } + + // SAFETY: no preconditions + let _ = ready.send(Ok(unsafe { GetCurrentThreadId() })); + + let mut message = MSG::default(); + // SAFETY: the standard message loop; `WM_QUIT` ends it + unsafe { + while GetMessageW(&raw mut message, None, 0, 0).as_bool() { + let _ = TranslateMessage(&raw const message); + DispatchMessageW(&raw const message); + } + let _ = UnhookWinEvent(hook); + } +} + +/// An Event Log subscription, delivered on a thread of the system's. +struct Subscription { + handle: EVT_HANDLE, + /// The `Arc` the callback was given, to be released after it is closed. + context: *const TraceStream, +} + +// SAFETY: the handle is an opaque token and the context an `Arc` raw pointer used only to release it +unsafe impl Send for Subscription {} + +/// Render an event to its XML. +fn render(event: EVT_HANDLE) -> Option { + let (mut used, mut count) = (0_u32, 0_u32); + // SAFETY: the first call asks how much room is needed; it fails with that, which is the point + let _ = unsafe { + EvtRender( + None, + event, + EvtRenderEventXml.0, + 0, + None, + &raw mut used, + &raw mut count, + ) + }; + if used == 0 { + return None; + } + + let mut buffer = vec![0_u16; (used as usize).div_ceil(2)]; + // SAFETY: the buffer is `used` bytes, as asked + unsafe { + EvtRender( + None, + event, + EvtRenderEventXml.0, + used, + Some(buffer.as_mut_ptr().cast()), + &raw mut used, + &raw mut count, + ) + } + .ok()?; + + let length = buffer + .iter() + .position(|unit| *unit == 0) + .unwrap_or(buffer.len()); + Some(String::from_utf16_lossy(&buffer[..length])) +} + +unsafe extern "system" fn on_event_log( + action: EVT_SUBSCRIBE_NOTIFY_ACTION, + context: *const c_void, + event: EVT_HANDLE, +) -> u32 { + if action != EvtSubscribeActionDeliver { + return 0; + } + + // SAFETY: `context` is the stream pointer `subscribe` gave, which outlives the subscription + let Some(stream) = (unsafe { context.cast::().as_ref() }) else { + return 0; + }; + let host_ns = clock::mono_now_ns(); + let wall_us = clock::wall_now_us(); + + if let Some(summary) = render(event).as_deref().and_then(summarize_event_xml) { + let pid = summary.pid.unwrap_or(0); + stream.write(&TraceRecord { + host_ns, + wall_us, + pid, + process: u32::try_from(pid) + .ok() + .and_then(super::apps::process_name) + .map_or_else(String::new, |name| format!("{name}.exe")), + message: format!( + "{} event {}{}{}", + summary.provider, + summary.event_id, + if summary.data.is_empty() { "" } else { ": " }, + summary.data.join("; ") + ), + category: summary.event_id, + subsystem: summary.provider, + level: summary.level, + }); + } + + 0 +} + +/// What the System log is asked for: warnings and errors from anyone, and the providers that talk +/// about displays, power and the GPU at any level. +const QUERIES: &[&str] = &[ + "*[System[Level=1 or Level=2 or Level=3]]", + "*[System[(Provider[@Name='Microsoft-Windows-Kernel-Power' or \ + @Name='Microsoft-Windows-Kernel-PnP' or @Name='Microsoft-Windows-DxgKrnl' or \ + @Name='Display' or @Name='Microsoft-Windows-Dwm-Core']) and (Level=0 or Level=4 or Level=5)]]", +]; + +fn subscribe(stream: &Arc, query: &str) -> Result { + let context = Arc::into_raw(stream.clone()); + // SAFETY: the callback only reads `context`, which is released after the subscription closes + let handle = unsafe { + EvtSubscribe( + None, + None, + &HSTRING::from("System"), + &HSTRING::from(query), + None, + Some(context.cast()), + Some(on_event_log), + EvtSubscribeToFutureEvents.0, + ) + }; + + match handle { + Ok(handle) => Ok(Subscription { handle, context }), + Err(error) => { + // SAFETY: not subscribed, so the pointer was never given away + drop(unsafe { Arc::from_raw(context) }); + Err(format!("{error}")) + } + } +} + +/// The running taps, listening until dropped. +/// +/// Dropping them stops hearing first (the Event Log subscriptions are closed, then the hook is +/// removed), then lets what was already heard be written, so nothing arrives after the drop +/// returns. +pub struct Taps { + hook_thread: Option<(u32, JoinHandle<()>)>, + sink: Option>, + subscriptions: Vec, +} + +impl Drop for Taps { + fn drop(&mut self) { + // stop hearing first, then let what was heard be written + for subscription in self.subscriptions.drain(..) { + // SAFETY: the subscription was made by `subscribe`; once closed no callback is running + // or will run, so the context can be released + unsafe { + let _ = EvtClose(subscription.handle); + drop(Arc::from_raw(subscription.context)); + } + } + + if let Some((thread_id, thread)) = self.hook_thread.take() { + // SAFETY: posting a quit to the hook thread's queue + let _ = unsafe { PostThreadMessageW(thread_id, WM_QUIT, WPARAM(0), LPARAM(0)) }; + let _ = thread.join(); + } + // the hook is gone, so no more is sent; closing the channel ends the sink + if let Some(heard) = HEARD.get() { + *heard.lock() = None; + } + if let Some(sink) = self.sink.take() { + let _ = sink.join(); + } + } +} + +/// Starts both taps, writing `WinEvents` into `system` and Event Log records into `event_log`. +/// +/// Returns the running [`Taps`], always `Some` on Windows, and the problems met: one entry in words +/// for each tap that could not start, beginning `winevents:` for the hook (or its thread) and +/// `eventlog:` for a subscription that could not be made. One that cannot start is named in the +/// problems and the other carries on. Two Event Log queries are made (warnings and errors from +/// any provider, and the display, power and GPU providers at the other levels), so `eventlog:` can +/// appear twice. On macOS this starts nothing and returns `None`. +#[must_use] +pub fn start(system: Arc, event_log: Arc) -> (Option, Vec) { + let mut problems = Vec::new(); + + let (heard_tx, heard_rx) = crossbeam_channel::unbounded(); + *HEARD.get_or_init(|| Mutex::new(None)).lock() = Some(heard_tx); + + let sink_stream = system.clone(); + let sink_thread = std::thread::Builder::new() + .name("komorebi-recorder-trace-sink".to_string()) + .spawn(move || sink(&heard_rx, &sink_stream)) + .ok(); + + let (ready_tx, ready_rx) = std::sync::mpsc::channel(); + let hook = std::thread::Builder::new() + .name("komorebi-recorder-winevents".to_string()) + .spawn(move || hook_thread(&ready_tx)) + .ok() + .and_then(|thread| match ready_rx.recv() { + Ok(Ok(thread_id)) => Some((thread_id, thread)), + Ok(Err(reason)) => { + problems.push(format!("winevents: {reason}")); + let _ = thread.join(); + None + } + Err(_) => { + problems.push("winevents: the hook thread ended before it was ready".to_string()); + None + } + }); + + let mut subscriptions = Vec::new(); + for query in QUERIES { + match subscribe(&event_log, query) { + Ok(subscription) => subscriptions.push(subscription), + Err(reason) => problems.push(format!("eventlog: could not subscribe ({reason})")), + } + } + + let taps = Taps { + hook_thread: hook, + sink: sink_thread, + subscriptions, + }; + (Some(taps), problems) +} diff --git a/komorebi-recorder/src/session.rs b/komorebi-recorder/src/session.rs index 11250b9f..b097042b 100644 --- a/komorebi-recorder/src/session.rs +++ b/komorebi-recorder/src/session.rs @@ -12,6 +12,7 @@ use crate::sources::komorebi_log::DetectedLevel; use crate::sources::komorebi_log::LogSegment; use crate::sources::komorebi_version::KomorebiVersion; use crate::sources::managed_apps::AppRecord; +use crate::sources::oslog::StreamInfo; use chrono::DateTime; use chrono::Utc; use color_eyre::eyre; @@ -188,6 +189,8 @@ pub struct Manifest { pub video_end_mach_ns: Option, /// The byte ranges of komorebi's log that were recorded, which together make `komorebi.log`. pub log_segments: Vec, + /// The OS trace streams that were recorded, one per file under `oslog/`. + pub oslog: Vec, /// The applications that own windows komorebi manages, which each get an OS trace stream of their own on a Mac. pub apps: Vec, /// What was recorded of komorebi's subscriber events. @@ -223,6 +226,7 @@ impl Manifest { video_t0_mach_ns: None, video_end_mach_ns: None, log_segments: Vec::new(), + oslog: Vec::new(), apps: Vec::new(), events: EventSummary::default(), sync_quality: "host-clock".to_string(), diff --git a/komorebi-recorder/src/sources/mod.rs b/komorebi-recorder/src/sources/mod.rs index 86f6c748..de2cdbf3 100644 --- a/komorebi-recorder/src/sources/mod.rs +++ b/komorebi-recorder/src/sources/mod.rs @@ -11,6 +11,8 @@ //! |---|---|---| //! | [`komorebi_events`] | `events.jsonl` (one JSON object per line), `states/.json` | both hosts | //! | `komorebi_log` | `komorebi.log` (a byte-for-byte slice of komorebi's own log) | both hosts | +//! | `oslog` | `oslog/*.ndjson`, one `log stream` per seam (komorebi, the system, each managed app) | macOS | +//! | `wintrace` | `oslog/system.ndjson` (`WinEvents`) and `oslog/eventlog.ndjson` (Event Log) | Windows | //! | `komorebi_version` | no file: asks komorebi's binary what it is, for the manifest | both hosts | //! | `managed_apps` | no file: decides which processes get a trace of their own | macOS | //! @@ -38,3 +40,5 @@ pub mod komorebi_events; pub mod komorebi_log; pub mod komorebi_version; pub mod managed_apps; +pub mod oslog; +pub mod wintrace; diff --git a/komorebi-recorder/src/sources/oslog.rs b/komorebi-recorder/src/sources/oslog.rs new file mode 100644 index 00000000..3192cc6e --- /dev/null +++ b/komorebi-recorder/src/sources/oslog.rs @@ -0,0 +1,1337 @@ +//! The macOS unified log, captured as a small set of `log stream` child processes. +//! +//! Instead of one mixed firehose there is one stream per *seam* that matters, each teed +//! untouched into its own file under `oslog/`: +//! +//! | stream | predicate | shows | +//! |---|---|---| +//! | `komorebi` | `processID == ` | system frameworks as the daemon sees them | +//! | `system` | AX / `HIServices` / workspace subsystems | the system side in between | +//! | `app:*` | `processID == `, one per managed app | the same frameworks from the app's side | +//! +//! Debug-level events only exist live (not in `log show`), which is why this streams rather than +//! querying afterwards. `log stream` does not need root; `` values stay redacted. +//! +//! # Files written +//! +//! | file | stream | `source` label | +//! |---|---|---| +//! | `oslog/komorebi.ndjson` | komorebi's process | `oslog:komorebi` | +//! | `oslog/komorebi-.ndjson` | a komorebi that was started during the recording, one file per process after the first | `oslog:komorebi` | +//! | `oslog/system.ndjson` | the `system` stream | `oslog:system` | +//! | `oslog/apps/-.ndjson` | one managed process; `` is made safe for a file name by [`sanitize_file_name`] | `oslog:app:` | +//! | `oslog/all.ndjson` | an unfiltered, system-wide stream (`--oslog-all`) | `oslog:all` | +//! +//! Each file is NDJSON: one JSON object per line, exactly as `log stream --style ndjson` printed +//! it. Lines that do not start with `{` are not written (the `Filtering the log data using ...` +//! header is kept in the manifest's [`StreamInfo::header`] instead). [`OsLogRecord`] names the keys +//! the recorder reads from a record; a Mac record has many more, which stay in the file. A +//! `source` label is what the timeline and the investigation commands call the stream. +//! +//! A `log stream` child that exits is started again into the same file, appending, so nothing +//! already captured is touched; the gap is reported as an incident ([`StreamSet::reap`]). One that +//! dies within seconds of starting never worked (a bad predicate, no access to the log) and is +//! reported lost instead of restarted in a loop. +//! +//! # Hosts +//! +//! Only macOS records with this module: [`StreamSet`] runs `/usr/bin/log`. The reading side +//! ([`OsLogRecord`], [`extract_time_ns`]) is the same on every host, because the Windows OS trace +//! (`wintrace`) writes its records in this shape, under the same `oslog/` directory, so that a +//! session recorded on either host is read the same way. A record's time is either `machTimestamp` +//! (a tick count of the Mac's clock) or `hostNs` (already nanoseconds on the master clock). +//! +//! # The `system` predicate +//! +//! The default `system` predicate was chosen by measuring event volume (debug level, 15 s, a real +//! desktop running komorebi): +//! +//! | candidate | events/s | MB/min | +//! |---|---:|---:| +//! | `com.apple.accessibility*` | 0.4 | 0.02 | +//! | `com.apple.SkyLight` | 2.4 | 0.14 | +//! | axserver / `HIServices` / workspace | 0 | 0 | +//! | `com.apple.launchservices` (system-wide) | 497 | 29.0 | +//! | `com.apple.runningboard` (system-wide) | 289 | 16.0 | +//! | `WindowServer` process (all subsystems) | ~170 | ~10 | +//! +//! so the cheap, relevant ones are the default and the noisy daemons are opt-in with +//! `--system-process`. (The three subsystems named in the original Console filters are silent in +//! practice, but cost nothing and may carry traffic on other macOS versions.) + +use crate::clock; +use crate::incidents::Draft; +use crate::incidents::kind; +use crate::platform::process; +use clap::ValueEnum; +use color_eyre::eyre; +use color_eyre::eyre::WrapErr; +use parking_lot::Mutex; +use serde::Deserialize; +use serde::Serialize; +use std::fs::File; +use std::io::BufRead; +use std::io::BufReader; +use std::io::BufWriter; +use std::io::Read; +use std::io::Write; +use std::path::Path; +use std::process::Child; +use std::process::Command; +use std::process::Stdio; +use std::sync::Arc; +use std::sync::atomic::AtomicU64; +use std::sync::atomic::Ordering; +use std::thread::JoinHandle; +use std::time::Duration; +use std::time::Instant; + +/// The exact subsystems that carry the accessibility / window-server conversation, which the +/// `system` stream follows. [`system_predicate`] matches each of them. +pub const SYSTEM_SUBSYSTEMS: &[&str] = &[ + "com.apple.accessibility.axserver", + "com.apple.HIServices", + "com.apple.workspace", + "com.apple.SkyLight", +]; + +/// Subsystem prefixes that are also part of it (`com.apple.accessibility.universalaccess`, ...). +/// [`system_predicate`] matches any subsystem that begins with one. +pub const SYSTEM_SUBSYSTEM_PREFIXES: &[&str] = &["com.apple.accessibility"]; + +/// How much of the unified log a stream asks for: the `--level` of `log stream`, which includes +/// events at and below the given level. +/// +/// The default is [`OsLogLevel::Debug`]. Serialized, and spelled on the command line, in lowercase: +/// `default`, `info`, `debug`. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, ValueEnum)] +#[serde(rename_all = "lowercase")] +pub enum OsLogLevel { + /// Only default-level events: the least. + Default, + /// Default-level and info-level events. + Info, + /// Default-, info- and debug-level events. Debug events exist only live, so this is the level + /// that shows what the frameworks say about each call. + #[default] + Debug, +} + +impl OsLogLevel { + fn as_arg(self) -> &'static str { + match self { + OsLogLevel::Default => "default", + OsLogLevel::Info => "info", + OsLogLevel::Debug => "debug", + } + } +} + +/// Which `log stream` child this is, and which timeline source its records belong to. +/// +/// The spec is stored in the manifest, flattened into the stream's [`StreamInfo`]. Build one with +/// [`komorebi_spec`], [`system_spec`], [`app_spec`] or [`all_spec`]. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct StreamSpec { + /// The stream's name, unique within a recording: `komorebi` or `komorebi-`, `system`, + /// `app:-` or `all`. + pub name: String, + /// The timeline source label: `oslog:komorebi`, `oslog:system`, `oslog:app:`, `oslog:all`. + pub source: String, + /// The `--predicate` given to `log stream`. Empty for a Windows trace stream, which has none. + pub predicate: String, + /// The `--level` given to `log stream`. A Windows trace stream records `debug` here, which + /// means nothing there. + pub level: OsLogLevel, + /// Path of the raw ndjson relative to the session directory. + pub file: String, + /// The process the stream follows. `None` for a stream that follows no single process + /// (`system`, `all`). + pub pid: Option, +} + +fn escape_predicate(value: &str) -> String { + value.replace('\\', "\\\\").replace('"', "\\\"") +} + +/// Returns the predicate that selects one process's events: `processID == `. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::sources::oslog::pid_predicate; +/// +/// assert_eq!(pid_predicate(42), "processID == 42"); +/// ``` +#[must_use] +pub fn pid_predicate(pid: i32) -> String { + format!("processID == {pid}") +} + +/// Returns the predicate for the `system` stream: the AX/workspace subsystems plus any explicitly +/// requested daemons. +/// +/// It is `subsystem IN {...}` over [`SYSTEM_SUBSYSTEMS`], then `OR subsystem BEGINSWITH ""` +/// for each of [`SYSTEM_SUBSYSTEM_PREFIXES`], then `OR process == ""` for each name in +/// `extra_processes`. A name is quoted, with `\` and `"` in it escaped. The daemons are opt-in +/// because they are noisy (see the module docs for the measured volumes). +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::sources::oslog::system_predicate; +/// +/// let plain = system_predicate(&[]); +/// assert!(plain.starts_with("subsystem IN {")); +/// assert!(plain.contains(r#"OR subsystem BEGINSWITH "com.apple.accessibility""#)); +/// assert!(!plain.contains("process ==")); +/// +/// let with_daemon = system_predicate(&["WindowServer".to_string()]); +/// assert!(with_daemon.ends_with(r#" OR process == "WindowServer""#)); +/// ``` +#[must_use] +pub fn system_predicate(extra_processes: &[String]) -> String { + let subsystems = SYSTEM_SUBSYSTEMS + .iter() + .map(|subsystem| format!("\"{subsystem}\"")) + .collect::>() + .join(", "); + + let mut predicate = format!("subsystem IN {{{subsystems}}}"); + for prefix in SYSTEM_SUBSYSTEM_PREFIXES { + predicate.push_str(&format!(" OR subsystem BEGINSWITH \"{prefix}\"")); + } + + for process in extra_processes { + predicate.push_str(&format!(" OR process == \"{}\"", escape_predicate(process))); + } + + predicate +} + +/// Makes a process name safe to use as a file name. +/// +/// Every character other than an ASCII letter or digit, `-`, `_` and `.` becomes `_`, and leading +/// and trailing `.` and `_` are trimmed, so the result cannot name a parent directory. A name with +/// nothing left is `app`. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::sources::oslog::sanitize_file_name; +/// +/// assert_eq!(sanitize_file_name("Brave Beta"), "Brave_Beta"); +/// assert_eq!(sanitize_file_name("../../etc/passwd"), "etc_passwd"); +/// assert_eq!(sanitize_file_name("///"), "app"); +/// ``` +#[must_use] +pub fn sanitize_file_name(name: &str) -> String { + let cleaned: String = name + .chars() + .map(|c| { + if c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.') { + c + } else { + '_' + } + }) + .collect(); + + let trimmed = cleaned.trim_matches(|c| c == '.' || c == '_'); + if trimmed.is_empty() { + "app".to_string() + } else { + trimmed.to_string() + } +} + +/// Returns the stream for komorebi's process. +/// +/// komorebi can be restarted during a recording; each new process gets its own file +/// (`oslog/komorebi-.ndjson`) under the same `oslog:komorebi` source, and the first keeps the +/// plain name. `first` says whether this is the first komorebi process of the recording. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::sources::oslog::{OsLogLevel, komorebi_spec}; +/// +/// let first = komorebi_spec(100, OsLogLevel::Debug, true); +/// assert_eq!((first.name.as_str(), first.file.as_str()), ("komorebi", "oslog/komorebi.ndjson")); +/// +/// // komorebi was restarted: same source, a file of its own +/// let restarted = komorebi_spec(200, OsLogLevel::Debug, false); +/// assert_eq!(restarted.source, first.source); +/// assert_eq!(restarted.file, "oslog/komorebi-200.ndjson"); +/// assert_eq!(restarted.predicate, "processID == 200"); +/// ``` +#[must_use] +pub fn komorebi_spec(pid: i32, level: OsLogLevel, first: bool) -> StreamSpec { + StreamSpec { + name: if first { + "komorebi".to_string() + } else { + format!("komorebi-{pid}") + }, + source: "oslog:komorebi".to_string(), + predicate: pid_predicate(pid), + level, + file: if first { + "oslog/komorebi.ndjson".to_string() + } else { + format!("oslog/komorebi-{pid}.ndjson") + }, + pid: Some(pid), + } +} + +/// Returns the `system` stream for `predicate` (see [`system_predicate`]): source `oslog:system`, +/// file `oslog/system.ndjson`, following no single process. +#[must_use] +pub fn system_spec(predicate: String, level: OsLogLevel) -> StreamSpec { + StreamSpec { + name: "system".to_string(), + source: "oslog:system".to_string(), + predicate, + level, + file: "oslog/system.ndjson".to_string(), + pid: None, + } +} + +/// Returns the stream for one managed process: named `app:-`, source `oslog:app:` +/// and file `oslog/apps/-.ndjson` with the name made safe by [`sanitize_file_name`]. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::sources::oslog::{OsLogLevel, app_spec}; +/// +/// let spec = app_spec("Brave Beta", 1234, OsLogLevel::Debug); +/// assert_eq!(spec.name, "app:Brave Beta-1234"); +/// assert_eq!(spec.source, "oslog:app:Brave Beta"); +/// assert_eq!(spec.file, "oslog/apps/Brave_Beta-1234.ndjson"); +/// assert_eq!(spec.predicate, "processID == 1234"); +/// assert_eq!(spec.pid, Some(1234)); +/// ``` +#[must_use] +pub fn app_spec(name: &str, pid: i32, level: OsLogLevel) -> StreamSpec { + let file_name = sanitize_file_name(name); + StreamSpec { + name: format!("app:{name}-{pid}"), + source: format!("oslog:app:{name}"), + predicate: pid_predicate(pid), + level, + file: format!("oslog/apps/{file_name}-{pid}.ndjson"), + pid: Some(pid), + } +} + +/// Returns the unfiltered, system-wide stream (`--oslog-all`): source `oslog:all`, file +/// `oslog/all.ndjson`. It is very large (about a gigabyte a minute, measured on a real desktop). +#[must_use] +pub fn all_spec(level: OsLogLevel) -> StreamSpec { + StreamSpec { + name: "all".to_string(), + source: "oslog:all".to_string(), + // `log stream` requires a predicate to be unfiltered-by-process; this matches everything + predicate: "processID > 0".to_string(), + level, + file: "oslog/all.ndjson".to_string(), + pid: None, + } +} + +/// What the recorder keeps of each unified-log record for indexing and display: the keys it reads +/// from a line of an `oslog/` file. +/// +/// The same keys are read from a Mac's `log stream` record and from a Windows trace record +/// (`wintrace`). Every key is optional on reading: one that is missing reads as `0`, empty or +/// `None`. The names in brackets are the JSON keys. +/// +/// # Example +/// +/// A Mac record carries `machTimestamp`, a Windows record carries `hostNs`: +/// +/// ```rust +/// use komorebi_recorder::sources::oslog::OsLogRecord; +/// +/// let mac = OsLogRecord::parse( +/// r#"{"machTimestamp":29042701633017,"timestamp":"2026-10-26 12:48:36.736892-0700","processID":41666,"processImagePath":"/usr/local/bin/komorebi","subsystem":"com.apple.defaults","category":"User Defaults","messageType":"Debug","eventMessage":"found no value for key X"}"#, +/// ) +/// .ok_or("not a record")?; +/// assert_eq!((mac.pid, mac.process_name()), (41666, "komorebi")); +/// assert_eq!((mac.subsystem.as_str(), mac.mach_ticks), ("com.apple.defaults", 29_042_701_633_017)); +/// assert_eq!(mac.host_ns, None); +/// +/// let windows = OsLogRecord::parse( +/// r#"{"hostNs":5000000000,"processID":4242,"processImagePath":"chrome.exe","subsystem":"winevent","eventMessage":"ObjectShow hwnd=0x1f2a"}"#, +/// ) +/// .ok_or("not a record")?; +/// assert_eq!(windows.host_ns, Some(5_000_000_000)); +/// assert_eq!(windows.process_name(), "chrome.exe"); +/// # Ok::<(), Box>(()) +/// ``` +#[derive(Debug, Clone, Deserialize)] +pub struct OsLogRecord { + /// `machTimestamp`: the Mac's tick count of the master clock (not nanoseconds: it is converted + /// with the session's [`Timebase`](crate::clock::Timebase)). `0` where the record has none, + /// which is every record the Windows trace writes. + #[serde(rename = "machTimestamp", default)] + pub mach_ticks: u64, + /// `hostNs`: the record's time on the master clock, in nanoseconds, where the writer already + /// had it there (the Windows OS trace); the Mac's records carry `machTimestamp` instead. + #[serde(rename = "hostNs", default)] + pub host_ns: Option, + /// `timestamp`: the record's wall-clock time as text, `2026-10-26 12:48:36.736892-0700`: local + /// time with a UTC offset on a Mac, UTC (`+0000`) in a Windows trace record. + #[serde(default)] + pub timestamp: String, + /// `processID`: the process that logged the record. + #[serde(rename = "processID", default)] + pub pid: i64, + /// `processImagePath`: the program's path on a Mac; a bare program name (`chrome.exe`) in a + /// Windows trace record, empty if the program could not be found. + #[serde(rename = "processImagePath", default)] + pub process_image_path: String, + /// `subsystem`: the unified log subsystem (`com.apple.SkyLight`); `winevent` or the Event Log + /// provider's name in a Windows trace record. + #[serde(default)] + pub subsystem: String, + /// `category`: the log category within the subsystem; the `WinEvent`'s name or the Event Log + /// event id in a Windows trace record. + #[serde(default)] + pub category: String, + /// `messageType`: `Default`, `Info`, `Debug`, `Error` or `Fault`. A Windows trace record uses + /// `Debug`, `Info`, `Error` and `Fault`. + #[serde(rename = "messageType", default)] + pub message_type: String, + /// `eventMessage`: the message text, with `` values redacted on a Mac. + #[serde(rename = "eventMessage", default)] + pub message: String, +} + +impl OsLogRecord { + /// Parses one line of an `oslog/` file. + /// + /// Returns `None` if the line does not start with `{` (such as the `Filtering the log data + /// ...` header of `log stream`) or is not valid JSON, or if a key the record reads has the + /// wrong type. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::sources::oslog::OsLogRecord; + /// + /// assert!(OsLogRecord::parse(r#"{"processID":1,"eventMessage":"hello"}"#).is_some()); + /// assert!(OsLogRecord::parse(r#"Filtering the log data using "processID == 1""#).is_none()); + /// assert!(OsLogRecord::parse("").is_none()); + /// assert!(OsLogRecord::parse("{not json").is_none()); + /// ``` + #[must_use] + pub fn parse(line: &str) -> Option { + if !line.starts_with('{') { + return None; + } + + serde_json::from_str(line).ok() + } + + /// Returns the record's time on the master clock, in nanoseconds: `hostNs` where the record has + /// it, else `machTimestamp` converted with the timebase of the machine this runs on. + /// + /// The conversion uses this machine's timebase, which is only right for a record written on + /// this machine. To read a session recorded elsewhere, use [`extract_time_ns`] with the + /// session's own timebase (the manifest's `timebase`). + #[must_use] + pub fn mach_ns(&self) -> u64 { + self.host_ns + .unwrap_or_else(|| clock::timebase().ticks_to_ns(self.mach_ticks)) + } + + /// Returns the program's name: the last component of `processImagePath`, split at `/` or `\`. + /// A path on a Mac and a bare name on Windows both give the program's file name. + #[must_use] + pub fn process_name(&self) -> &str { + // a path on a Mac, a bare program name on Windows (or a path with backslashes) + self.process_image_path + .rsplit(['/', '\\']) + .next() + .unwrap_or(&self.process_image_path) + } +} + +/// Returns a raw line's time on the master clock in nanoseconds, without a full JSON parse. +/// +/// This is its `hostNs` where it has one, else its `machTimestamp` tick count converted with +/// `timebase`, which is the session's (a session is read on whichever machine, so the reader's own +/// timebase would be wrong). +/// +/// `None` if the line has neither key followed by digits. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::clock::Timebase; +/// use komorebi_recorder::sources::oslog::extract_time_ns; +/// +/// // a Mac record: ticks, converted with the session's timebase (here 125/3, as on Apple silicon) +/// let timebase = Timebase { numer: 125, denom: 3 }; +/// assert_eq!(extract_time_ns(br#"{"machTimestamp":300,"processID":1}"#, timebase), Some(12_500)); +/// +/// // a Windows record: already nanoseconds, whatever the timebase +/// assert_eq!(extract_time_ns(br#"{"hostNs":5000000000}"#, timebase), Some(5_000_000_000)); +/// +/// assert_eq!(extract_time_ns(br#"{"nothing":1}"#, timebase), None); +/// ``` +#[must_use] +pub fn extract_time_ns(line: &[u8], timebase: clock::Timebase) -> Option { + extract_digits(line, b"\"hostNs\":") + .or_else(|| extract_mach_ticks(line).map(|ticks| timebase.ticks_to_ns(ticks))) +} + +fn extract_digits(line: &[u8], key: &[u8]) -> Option { + let start = line.windows(key.len()).position(|window| window == key)? + key.len(); + let digits: Vec = line[start..] + .iter() + .copied() + .take_while(u8::is_ascii_digit) + .collect(); + + std::str::from_utf8(&digits).ok()?.parse().ok() +} + +/// Cheaply pulls `"machTimestamp":` out of a raw line without a full JSON parse, and +/// returns the tick count. The first such key in the line is the one read. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::sources::oslog::extract_mach_ticks; +/// +/// assert_eq!( +/// extract_mach_ticks(br#"{"machTimestamp":29042701633017,"processID":41666}"#), +/// Some(29_042_701_633_017) +/// ); +/// assert_eq!(extract_mach_ticks(br#"{"nothing":1}"#), None); +/// ``` +#[must_use] +pub fn extract_mach_ticks(line: &[u8]) -> Option { + const KEY: &[u8] = b"\"machTimestamp\":"; + let start = line.windows(KEY.len()).position(|window| window == KEY)? + KEY.len(); + let digits: Vec = line[start..] + .iter() + .copied() + .take_while(u8::is_ascii_digit) + .collect(); + + std::str::from_utf8(&digits).ok()?.parse().ok() +} + +#[derive(Debug, Default)] +struct Counters { + lines: AtomicU64, + bytes: AtomicU64, + /// `0` until the stream's header line has been seen. + ready_mach_ns: AtomicU64, + first_event_mach_ns: AtomicU64, + last_event_mach_ns: AtomicU64, +} + +/// The outcome of one stream, recorded in the session manifest (`session.json`, key `oslog`). +/// +/// The stream's [`StreamSpec`] is flattened into it, so a manifest entry has the spec's keys +/// (`name`, `source`, `predicate`, `level`, `file`, `pid`) and then the ones below. Times are +/// nanoseconds on the host's master monotonic clock. The Windows OS trace reports its two files +/// the same way (see `wintrace`). +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct StreamInfo { + /// Which stream this is. + #[serde(flatten)] + pub spec: StreamSpec, + /// When the `log stream` child was spawned (master clock). + pub spawned_mach_ns: u64, + /// When it announced it was filtering; events before this are not in the file. `None` if it + /// never did. + pub ready_mach_ns: Option, + /// The `Filtering the log data using ...` line `log stream` printed. Only the final report + /// has it; a checkpoint taken while recording does not. + pub header: Option, + /// How many records are in the file. + pub events: u64, + /// How many bytes of records are in the file. + pub bytes: u64, + /// The time of the first record in the file, from its `machTimestamp`. `None` if there is + /// none. + pub first_event_mach_ns: Option, + /// The time of the last record written so far, from its `machTimestamp`. `None` if there is + /// none. + pub last_event_mach_ns: Option, + /// How many times the `log stream` child died and was brought back. Each restart leaves a + /// gap in the file whose length is in the incident log. + #[serde(default)] + pub restarts: u32, + /// Why the stream is not what was asked for, if it is not: the reason it was lost, how the + /// child failed, or what it wrote to its standard error. `None` for a healthy stream. + pub error: Option, +} + +/// A running stream's live counters, for the UI. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct StreamLive { + /// The stream's name ([`StreamSpec::name`]). + pub name: String, + /// Records written so far. + pub events: u64, + /// Bytes of records written so far. + pub bytes: u64, +} + +struct Running { + spec: StreamSpec, + child: Child, + reader: Option>>, + stderr: Option>, + counters: Arc, + spawned_mach_ns: u64, + started: Instant, + restarts: u32, + /// Set once the stream has died for good: the reason, and no further restarts. + lost: Option, +} + +/// How many times a stream that keeps dying is brought back before giving up on it. +const MAX_RESTARTS: u32 = 20; + +/// A stream that dies sooner than this after starting has not been working at all (a bad +/// predicate, no access to the log), so restarting it would only loop. +const MIN_HEALTHY_RUNTIME: Duration = Duration::from_secs(2); + +/// What a started `log stream` child consists of. +struct Launched { + child: Child, + reader: JoinHandle>, + stderr: JoinHandle, + spawned_mach_ns: u64, +} + +/// A set of concurrently running `log stream` children, each writing one stream's file. +/// +/// The recorder owns one set per recording and drives it: +/// +/// 1. [`spawn`](Self::spawn) starts a stream, and [`wait_ready`](Self::wait_ready) waits until every +/// stream is filtering, so that no event the recording cares about is missed at the start. +/// 2. [`reap`](Self::reap) is called regularly. It restarts a child that died, and reports the +/// streams that cannot be kept alive. +/// 3. [`snapshot`](Self::snapshot) and [`checkpoint`](Self::checkpoint) read the state without +/// stopping anything, for the live display and the manifest. +/// 4. [`stop`](Self::stop) ends every child and returns what each stream captured. Dropping a set +/// that still has children stops them, so abandoning a recording never leaves a `log stream` +/// behind. +/// +/// Every method takes `&self`: the set is safe to use from more than one thread. +/// +/// Only macOS can run the children, because they are `/usr/bin/log`; on any other host +/// [`spawn`](Self::spawn) returns an error. Each child runs in a process group of its own +/// ([`crate::platform::process::isolate`]), so a terminal Ctrl-C reaches only the recorder, which +/// then stops them in order instead of losing their last records. +/// +/// # Example +/// +/// Streams need the unified log, so this example only compiles. The behavior is covered by these +/// unit tests in this file, which skip themselves where `log stream` is not usable: +/// `a_log_stream_that_dies_is_restarted_into_the_same_file`, +/// `a_log_stream_that_never_worked_is_reported_lost_not_restarted_forever`, +/// `tee_keeps_records_and_splits_off_the_header` and `the_first_ready_time_survives_a_restart`. +/// +/// ```rust,no_run +/// use komorebi_recorder::sources::oslog::{OsLogLevel, StreamSet, app_spec}; +/// use std::path::Path; +/// use std::time::Duration; +/// +/// let set = StreamSet::new(Path::new("session")); +/// set.spawn(app_spec("Slack", 1234, OsLogLevel::Debug))?; +/// +/// // wait until `log stream` says it is filtering +/// let not_ready = set.wait_ready(Duration::from_secs(5)); +/// assert!(not_ready.is_empty(), "not ready: {not_ready:?}"); +/// +/// // ... record, calling `set.reap()` now and then ... +/// +/// for stream in set.stop() { +/// println!("{}: {} events in {}", stream.spec.name, stream.events, stream.spec.file); +/// } +/// # Ok::<(), Box>(()) +/// ``` +pub struct StreamSet { + session_dir: std::path::PathBuf, + running: Mutex>, +} + +impl StreamSet { + /// Creates an empty set whose streams write under `session_dir`. Nothing is started. + #[must_use] + pub fn new(session_dir: &Path) -> Self { + Self { + session_dir: session_dir.to_path_buf(), + running: Mutex::new(Vec::new()), + } + } + + /// Whether a stream with this name was already spawned. + #[must_use] + pub fn has(&self, name: &str) -> bool { + self.running + .lock() + .iter() + .any(|running| running.spec.name == name) + } + + /// Whether a stream for this process id was already spawned. + #[must_use] + pub fn has_pid(&self, pid: i32) -> bool { + self.running + .lock() + .iter() + .any(|running| running.spec.pid == Some(pid)) + } + + /// Start `log stream` for `spec`, writing its records to the spec's file: truncating it for a + /// new stream, appending for a restart so that nothing already captured is touched. + fn launch( + &self, + spec: &StreamSpec, + counters: &Arc, + append: bool, + ) -> eyre::Result { + let path = self.session_dir.join(&spec.file); + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent) + .wrap_err_with(|| format!("could not create {}", parent.display()))?; + } + + let file = if append { + std::fs::OpenOptions::new() + .create(true) + .append(true) + .open(&path) + } else { + File::create(&path) + } + .wrap_err_with(|| format!("could not open {}", path.display()))?; + + let spawned_mach_ns = clock::mono_now_ns(); + let mut command = Command::new("/usr/bin/log"); + command + .args([ + "stream", + "--style", + "ndjson", + "--level", + spec.level.as_arg(), + ]) + .args(["--predicate", &spec.predicate]) + .stdin(Stdio::null()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()); + // own process group, so a terminal Ctrl-C reaches only us and we can drain and stop these + // children in order instead of losing their tail + process::isolate(&mut command); + let mut child = command.spawn().wrap_err("could not run /usr/bin/log")?; + + let stdout = child + .stdout + .take() + .ok_or_else(|| eyre::Report::msg("log stream has no stdout"))?; + let mut stderr = child + .stderr + .take() + .ok_or_else(|| eyre::Report::msg("log stream has no stderr"))?; + + let reader_counters = counters.clone(); + let reader = std::thread::Builder::new() + .name(format!("oslog-{}", spec.name)) + .spawn(move || tee_stream(stdout, file, &reader_counters)) + .wrap_err("could not start the log reader thread")?; + + let stderr_reader = std::thread::spawn(move || { + let mut text = String::new(); + let _ = stderr.read_to_string(&mut text); + text + }); + + Ok(Launched { + child, + reader, + stderr: stderr_reader, + spawned_mach_ns, + }) + } + + /// Starts `log stream` for `spec` and adds it to the set. + /// + /// The stream's file (`spec.file`, under the session directory) is created, with its + /// directories, and truncated if it exists. The call returns as soon as the child is started: + /// that the predicate works and the stream is filtering is shown later, by + /// [`wait_ready`](Self::wait_ready) and [`reap`](Self::reap). Spawning a name that is already + /// in the set is not checked; use [`has`](Self::has) or [`has_pid`](Self::has_pid) first. + /// + /// # Errors + /// + /// Returns an error if + /// + /// - a directory for the file cannot be created, or the file cannot be opened, + /// - `/usr/bin/log` cannot be run, which is the case on every host but macOS, or its output + /// pipes cannot be taken, or + /// - the thread that copies its output cannot be started. + pub fn spawn(&self, spec: StreamSpec) -> eyre::Result<()> { + let counters = Arc::new(Counters::default()); + let launched = self.launch(&spec, &counters, false)?; + + self.running.lock().push(Running { + spec, + child: launched.child, + reader: Some(launched.reader), + stderr: Some(launched.stderr), + counters, + spawned_mach_ns: launched.spawned_mach_ns, + started: Instant::now(), + restarts: 0, + lost: None, + }); + + Ok(()) + } + + /// Notices `log stream` children that have exited on their own (logd restarting, the machine + /// waking from sleep) and brings them back, appending to the same file so nothing already + /// captured is lost. Events during the gap cannot be recovered, which is reported. + /// + /// Returns an incident for each stream that needed attention, for the caller to record: + /// + /// - [`kind::LOG_STREAM_RESTARTED`], for a child + /// that had run for at least two seconds and was started again. It says how long before the + /// exit the last event was captured, when there was one. + /// - [`kind::LOG_STREAM_LOST`] for a child that + /// exited within two seconds of starting, or of its last restart (it has not worked at all: + /// a bad predicate, no access to the log), that has already been restarted 20 times, or that + /// could not be started again. A lost stream is not tried again and not reported again, and + /// its reason is the [`StreamInfo::error`] of its reports. + /// + /// A healthy stream returns nothing. + pub fn reap(&self) -> Vec { + let mut drafts = Vec::new(); + let mut running = self.running.lock(); + + for stream in running.iter_mut().filter(|stream| stream.lost.is_none()) { + let Ok(Some(status)) = stream.child.try_wait() else { + continue; + }; + + let exited_at = clock::mono_now_ns(); + let _ = stream.reader.take().map(JoinHandle::join); + let stderr = stream + .stderr + .take() + .and_then(|reader| reader.join().ok()) + .unwrap_or_default(); + let stderr = stderr.trim(); + + let healthy = stream.started.elapsed() >= MIN_HEALTHY_RUNTIME; + if !healthy || stream.restarts >= MAX_RESTARTS { + let reason = if healthy { + format!( + "log stream kept dying (restarted {} times)", + stream.restarts + ) + } else { + format!("log stream exited immediately with {status}") + }; + let reason = if stderr.is_empty() { + reason + } else { + format!("{reason}: {stderr}") + }; + + drafts.push(Draft::new( + kind::LOG_STREAM_LOST, + format!("OS trace stream '{}': {reason}", stream.spec.name), + )); + stream.lost = Some(reason); + continue; + } + + let counters = stream.counters.clone(); + match self.launch(&stream.spec, &counters, true) { + Ok(launched) => { + stream.child = launched.child; + stream.reader = Some(launched.reader); + stream.stderr = Some(launched.stderr); + stream.started = Instant::now(); + stream.restarts += 1; + + let last_event = counters.last_event_mach_ns.load(Ordering::Relaxed); + let gap = if last_event == 0 { + String::new() + } else { + format!( + "; events between {:.1}s before this and the restart are missing", + exited_at.saturating_sub(last_event) as f64 / 1e9 + ) + }; + drafts.push(Draft::new( + kind::LOG_STREAM_RESTARTED, + format!( + "OS trace stream '{}' exited ({status}) and was restarted (restart {}){gap}", + stream.spec.name, stream.restarts + ), + )); + } + Err(error) => { + let reason = format!("could not restart log stream: {error:#}"); + drafts.push(Draft::new( + kind::LOG_STREAM_LOST, + format!("OS trace stream '{}': {reason}", stream.spec.name), + )); + stream.lost = Some(reason); + } + } + } + + drafts + } + + /// Blocks until every stream has announced that it is filtering, or `timeout` passes. Returns + /// the names of streams that were not ready in time; the vector is empty when all were. + /// + /// A stream is ready once `log stream` has printed its header line. A stream that dies before + /// it is filtering never becomes ready, so it is named when the time is up. + pub fn wait_ready(&self, timeout: Duration) -> Vec { + let deadline = Instant::now() + timeout; + loop { + let pending: Vec = self + .running + .lock() + .iter() + .filter(|running| running.counters.ready_mach_ns.load(Ordering::Relaxed) == 0) + .map(|running| running.spec.name.clone()) + .collect(); + + if pending.is_empty() || Instant::now() >= deadline { + return pending; + } + + std::thread::sleep(Duration::from_millis(10)); + } + } + + /// Returns each running stream's live counters, in the order they were spawned. + #[must_use] + pub fn snapshot(&self) -> Vec { + self.running + .lock() + .iter() + .map(|running| StreamLive { + name: running.spec.name.clone(), + events: running.counters.lines.load(Ordering::Relaxed), + bytes: running.counters.bytes.load(Ordering::Relaxed), + }) + .collect() + } + + fn info(stream: &Running, header: Option, error: Option) -> StreamInfo { + let counters = &stream.counters; + let nonzero = |value: u64| (value != 0).then_some(value); + + StreamInfo { + spec: stream.spec.clone(), + spawned_mach_ns: stream.spawned_mach_ns, + ready_mach_ns: nonzero(counters.ready_mach_ns.load(Ordering::Relaxed)), + header, + events: counters.lines.load(Ordering::Relaxed), + bytes: counters.bytes.load(Ordering::Relaxed), + first_event_mach_ns: nonzero(counters.first_event_mach_ns.load(Ordering::Relaxed)), + last_event_mach_ns: nonzero(counters.last_event_mach_ns.load(Ordering::Relaxed)), + restarts: stream.restarts, + error: error.or_else(|| stream.lost.clone()), + } + } + + /// Returns every stream's state so far, without stopping anything (for manifest checkpoints). + /// The `header` of each is `None` and its `error` is set only for a stream that was lost. + #[must_use] + pub fn checkpoint(&self) -> Vec { + self.running + .lock() + .iter() + .map(|stream| Self::info(stream, None, None)) + .collect() + } + + /// Terminates every child, drains what they had buffered, and reports each stream's outcome. + /// + /// Each child is sent `SIGTERM` and given three seconds to exit before it is killed. The + /// [`StreamInfo::error`] of a stream is set if its child failed for a reason other than being + /// told to stop, or wrote to its standard error. The set is empty afterwards, so a second call + /// returns nothing. + pub fn stop(&self) -> Vec { + let mut running = std::mem::take(&mut *self.running.lock()); + + for stream in &mut running { + process::terminate(&mut stream.child); + } + + running + .iter_mut() + .map(|stream| { + let deadline = Instant::now() + Duration::from_secs(3); + let status = loop { + match stream.child.try_wait() { + Ok(Some(status)) => break Some(status), + Ok(None) if Instant::now() < deadline => { + std::thread::sleep(Duration::from_millis(10)); + } + _ => { + let _ = stream.child.kill(); + break stream.child.wait().ok(); + } + } + }; + + let header = stream + .reader + .take() + .and_then(|reader| reader.join().ok().flatten()); + let stderr = stream + .stderr + .take() + .and_then(|reader| reader.join().ok()) + .unwrap_or_default(); + + // SIGTERM is how we stop it, so only other failures are interesting + let mut error = None; + if stream.lost.is_none() + && let Some(status) = status + && !status.success() + && !process::was_terminated(&status) + { + error = Some(format!("log stream exited with {status}")); + } + + let stderr = stderr.trim(); + if stream.lost.is_none() && !stderr.is_empty() { + error = Some(match error { + Some(existing) => format!("{existing}: {stderr}"), + None => stderr.to_string(), + }); + } + + Self::info(stream, header, error) + }) + .collect() + } +} + +impl Drop for StreamSet { + fn drop(&mut self) { + // never leave `log stream` children behind if recording is abandoned + if !self.running.lock().is_empty() { + let _ = self.stop(); + } + } +} + +/// Copy `log stream`'s stdout into `file`, keeping only ndjson records in the file, and return the +/// non-JSON "Filtering the log data using ..." header if one was printed. +fn tee_stream(stdout: impl Read, file: File, counters: &Counters) -> Option { + let mut reader = BufReader::with_capacity(64 * 1024, stdout); + let mut writer = BufWriter::with_capacity(64 * 1024, file); + let mut line = Vec::with_capacity(4096); + let mut header = None; + + loop { + line.clear(); + match reader.read_until(b'\n', &mut line) { + Ok(0) | Err(_) => break, + Ok(_) => {} + } + + if line.first() == Some(&b'{') { + if writer.write_all(&line).is_err() { + break; + } + + counters.lines.fetch_add(1, Ordering::Relaxed); + counters + .bytes + .fetch_add(line.len() as u64, Ordering::Relaxed); + + if let Some(ticks) = extract_mach_ticks(&line) { + let ns = clock::timebase().ticks_to_ns(ticks); + let _ = counters.first_event_mach_ns.compare_exchange( + 0, + ns, + Ordering::Relaxed, + Ordering::Relaxed, + ); + counters.last_event_mach_ns.store(ns, Ordering::Relaxed); + } + } else if header.is_none() { + header = Some(String::from_utf8_lossy(&line).trim().to_string()); + // only the first: later headers are restarts, and the manifest wants when events + // started being captured + let _ = counters.ready_mach_ns.compare_exchange( + 0, + clock::mono_now_ns(), + Ordering::Relaxed, + Ordering::Relaxed, + ); + } + + // flush whenever we have caught up with the pipe so a crash loses almost nothing + if reader.buffer().is_empty() { + let _ = writer.flush(); + } + } + + let _ = writer.flush(); + header +} + +#[cfg(test)] +mod tests { + use super::*; + + /// The shape `log stream --style ndjson` emits, captured from a real run (trimmed). + const FIXTURE: &str = r#"{"timezoneName":"","messageType":"Debug","eventType":"logEvent","source":null,"formatString":"found no value for key %{public}@","userID":501,"activityIdentifier":0,"subsystem":"com.apple.defaults","category":"User Defaults","threadID":132217281,"senderImageUUID":"ADB84143-D965-3B3D-9BA5-EAB165A96490","backtrace":{"frames":[{"imageOffset":2047056,"imageUUID":"ADB84143"}]},"bootUUID":"","processImagePath":"\/Users\/lgug2z\/.cargo\/bin\/komorebi","timestamp":"2026-10-26 12:48:36.736892-0700","senderImagePath":"\/System\/Library\/Frameworks\/CoreFoundation","machTimestamp":29042701633017,"eventMessage":"found no value for key NSPersistentUIShowQuietSafeQuitStatus","processImageUUID":"X","traceID":40312880901652996,"processID":41666,"senderProgramCounter":2047056,"parentActivityIdentifier":0}"#; + + #[test] + fn parses_a_real_record() { + let record = OsLogRecord::parse(FIXTURE).expect("record"); + assert_eq!(record.mach_ticks, 29_042_701_633_017); + assert_eq!(record.pid, 41666); + assert_eq!(record.subsystem, "com.apple.defaults"); + assert_eq!(record.category, "User Defaults"); + assert_eq!(record.process_name(), "komorebi"); + assert!(record.message.starts_with("found no value")); + assert_eq!(record.timestamp, "2026-10-26 12:48:36.736892-0700"); + } + + #[test] + fn non_json_lines_are_not_records() { + assert!(OsLogRecord::parse("Filtering the log data using \"processID == 1\"").is_none()); + assert!(OsLogRecord::parse("").is_none()); + assert!(OsLogRecord::parse("{not json").is_none()); + } + + #[test] + fn extracts_mach_ticks_without_a_full_parse() { + assert_eq!( + extract_mach_ticks(FIXTURE.as_bytes()), + Some(29_042_701_633_017) + ); + assert_eq!(extract_mach_ticks(b"{\"nothing\":1}"), None); + } + + #[test] + fn builds_predicates() { + assert_eq!(pid_predicate(42), "processID == 42"); + let system = system_predicate(&[]); + for subsystem in SYSTEM_SUBSYSTEMS { + assert!(system.contains(subsystem)); + } + assert!(system.contains("subsystem BEGINSWITH \"com.apple.accessibility\"")); + assert!(!system.contains("process ==")); + + let with_daemons = + system_predicate(&["WindowServer".to_string(), "weird\"name".to_string()]); + assert!(with_daemons.contains(" OR process == \"WindowServer\"")); + assert!(with_daemons.contains("weird\\\"name")); + } + + #[test] + fn sanitizes_app_names_for_files() { + assert_eq!(sanitize_file_name("Brave Beta"), "Brave_Beta"); + assert_eq!(sanitize_file_name("IntelliJ IDEA"), "IntelliJ_IDEA"); + assert_eq!(sanitize_file_name("../../etc/passwd"), "etc_passwd"); + assert_eq!(sanitize_file_name("///"), "app"); + assert_eq!(sanitize_file_name(""), "app"); + } + + #[test] + fn app_specs_are_labelled_by_exe_and_pid() { + let spec = app_spec("Brave Beta", 1234, OsLogLevel::Debug); + assert_eq!(spec.name, "app:Brave Beta-1234"); + assert_eq!(spec.source, "oslog:app:Brave Beta"); + assert_eq!(spec.file, "oslog/apps/Brave_Beta-1234.ndjson"); + assert_eq!(spec.predicate, "processID == 1234"); + } + + #[test] + fn tee_keeps_records_and_splits_off_the_header() { + let dir = + std::env::temp_dir().join(format!("komorebi-recorder-tee-{}", std::process::id())); + std::fs::create_dir_all(&dir).expect("dir"); + let path = dir.join("out.ndjson"); + + let input = format!("Filtering the log data using \"x\"\n{FIXTURE}\n{FIXTURE}\n"); + let counters = Counters::default(); + let header = tee_stream( + input.as_bytes(), + File::create(&path).expect("file"), + &counters, + ); + + assert_eq!( + header.as_deref(), + Some("Filtering the log data using \"x\"") + ); + assert_eq!(counters.lines.load(Ordering::Relaxed), 2); + assert_ne!(counters.ready_mach_ns.load(Ordering::Relaxed), 0); + assert_ne!(counters.first_event_mach_ns.load(Ordering::Relaxed), 0); + + let written = std::fs::read_to_string(&path).expect("read"); + assert_eq!(written.lines().count(), 2); + assert!(written.lines().all(|line| line.starts_with('{'))); + } + + fn temp(name: &str) -> std::path::PathBuf { + let dir = std::env::temp_dir().join(format!( + "komorebi-recorder-oslog-{name}-{}", + std::process::id() + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(dir.join("oslog/apps")).expect("dir"); + dir + } + + /// A real `log stream` on launchd that has become ready, or `None` where the unified log is + /// not readable (a sandboxed build), in which case there is nothing to test. + #[cfg(target_os = "macos")] + fn ready_stream(dir: &Path) -> Option { + let set = StreamSet::new(dir); + let usable = set.spawn(app_spec("launchd", 1, OsLogLevel::Debug)).is_ok() + && set.wait_ready(Duration::from_secs(5)).is_empty(); + if !usable { + eprintln!("skipping: `log stream` is not usable from this environment"); + let _ = set.stop(); + return None; + } + + Some(set) + } + + #[cfg(target_os = "macos")] + fn child_pid(set: &StreamSet) -> i32 { + set.running.lock()[0].child.id() as i32 + } + + #[cfg(target_os = "macos")] + #[test] + fn a_log_stream_that_dies_is_restarted_into_the_same_file() { + let dir = temp("restart"); + let Some(set) = ready_stream(&dir) else { + return; + }; + + // only a stream that had been healthy for a while is worth bringing back + std::thread::sleep(MIN_HEALTHY_RUNTIME + Duration::from_millis(300)); + let file = dir.join("oslog/apps/launchd-1.ndjson"); + std::fs::OpenOptions::new() + .append(true) + .open(&file) + .and_then(|mut file| { + std::io::Write::write_all(&mut file, b"{\"marker\":\"before the restart\"}\n") + }) + .expect("marker"); + + // logd restarts, or the machine wakes: the child is gone + // SAFETY: signalling a child process this test spawned + unsafe { libc::kill(child_pid(&set), libc::SIGKILL) }; + std::thread::sleep(Duration::from_millis(300)); + + let drafts = set.reap(); + assert_eq!(drafts.len(), 1, "{drafts:?}"); + assert_eq!(drafts[0].kind, kind::LOG_STREAM_RESTARTED); + assert!( + drafts[0].detail.contains("restarted"), + "{}", + drafts[0].detail + ); + + // it is running again, and what was captured before is untouched + assert!(set.wait_ready(Duration::from_secs(5)).is_empty()); + assert_eq!(set.checkpoint()[0].restarts, 1); + assert!(set.reap().is_empty(), "the replacement is healthy"); + + let infos = set.stop(); + assert_eq!(infos[0].restarts, 1); + assert!(infos[0].error.is_none(), "{:?}", infos[0].error); + let text = std::fs::read_to_string(&file).expect("read"); + assert!( + text.contains("before the restart"), + "the restart must append, not truncate" + ); + } + + #[test] + fn a_log_stream_that_never_worked_is_reported_lost_not_restarted_forever() { + let dir = temp("lost"); + let set = StreamSet::new(&dir); + let spec = StreamSpec { + name: "bad".to_string(), + source: "oslog:bad".to_string(), + predicate: "this is not ( a predicate".to_string(), + level: OsLogLevel::Debug, + file: "oslog/bad.ndjson".to_string(), + pid: None, + }; + + if set.spawn(spec).is_err() { + eprintln!("skipping: /usr/bin/log cannot be run from this environment"); + return; + } + + // an invalid predicate makes `log stream` exit straight away + std::thread::sleep(Duration::from_millis(800)); + + let drafts = set.reap(); + assert_eq!(drafts.len(), 1, "{drafts:?}"); + assert_eq!(drafts[0].kind, kind::LOG_STREAM_LOST); + assert!( + drafts[0].detail.contains("exited immediately"), + "{}", + drafts[0].detail + ); + + // and it is not tried again, nor reported again + assert!(set.reap().is_empty()); + let infos = set.stop(); + assert_eq!(infos[0].restarts, 0); + assert!( + infos[0] + .error + .as_deref() + .is_some_and(|error| error.contains("exited immediately")) + ); + } + + #[test] + fn the_first_ready_time_survives_a_restart() { + let counters = Counters::default(); + let _ = + counters + .ready_mach_ns + .compare_exchange(0, 111, Ordering::Relaxed, Ordering::Relaxed); + + // a restarted stream's header must not overwrite when events first started being captured + let input = "Filtering the log data using \"x\"\n"; + let dir = temp("ready"); + tee_stream( + input.as_bytes(), + File::create(dir.join("a.ndjson")).expect("file"), + &counters, + ); + assert_eq!(counters.ready_mach_ns.load(Ordering::Relaxed), 111); + } +} diff --git a/komorebi-recorder/src/sources/wintrace.rs b/komorebi-recorder/src/sources/wintrace.rs new file mode 100644 index 00000000..dd1df677 --- /dev/null +++ b/komorebi-recorder/src/sources/wintrace.rs @@ -0,0 +1,859 @@ +//! The OS trace on Windows. +//! +//! A Mac has a unified log to ask what the system did. Windows has no one place, so two things are +//! recorded into `oslog/` next to komorebi's own output, in the same shape the Mac's records have +//! so that the timeline, `search`, `at` and `trace --os` read them unchanged: +//! +//! - **what the OS told komorebi**: the `WinEvents` komorebi itself listens for (a window is shown, +//! hidden, cloaked, focused, moved, resized, renamed, destroyed), tapped with a hook of the +//! recorder's own, for every top-level window and not only the ones komorebi manages. komorebi +//! hears these from the same hook and filters what it acts on; seeing the unfiltered stream is +//! what answers "did Windows tell it?". `oslog/system.ndjson`, source `oslog:system`. +//! - **what Windows logged**: the System Event Log's warnings and errors, and the providers that +//! talk about displays, power and the GPU (a display driver reset, a Kernel-Power event, a +//! plug and play arrival). `oslog/eventlog.ndjson`, source `oslog:eventlog`. +//! +//! This module is the part that does not need Windows: the record format, deciding which noisy +//! events to fold together, reading an Event Log record's XML, and the files and counters. It +//! builds on every host, so a Windows session can be read anywhere. The taps themselves are in +//! [`crate::platform::trace`]; on a host other than Windows they start nothing. +//! +//! # Files written +//! +//! Both files are NDJSON: one JSON object per line. Each line has the keys of a Mac unified-log +//! record (see [`OsLogRecord`](crate::sources::oslog::OsLogRecord)), so every reader of the Mac's +//! trace reads these unchanged, with `hostNs` where the Mac has a tick count: +//! +//! | key | contents | +//! |---|---| +//! | `hostNs` | the time on the master clock, in nanoseconds (the master clock is `QueryPerformanceCounter` on Windows) | +//! | `timestamp` | the wall-clock time as `2026-10-27 12:34:56.123456+0000`, in UTC | +//! | `processID` | the process of the window or of the logger, `0` if unknown | +//! | `processImagePath` | the program's file name with `.exe` (`chrome.exe`), empty if it could not be found | +//! | `subsystem` | `winevent` in `system.ndjson`; the Event Log provider's name in `eventlog.ndjson` | +//! | `category` | the `WinEvent`'s name (`ObjectShow`), or the Event Log event id (`506`) | +//! | `messageType` | `Debug`, `Info`, `Error` or `Fault` | +//! | `eventMessage` | ` hwnd=0x class=` for a `WinEvent`; ` event : ` for an Event Log record | +//! +//! The manifest lists the two as streams named `winevents` and `eventlog` ([`TraceSet`]). +//! +//! # What is recorded +//! +//! - **`WinEvents`**: only events about a window itself (not the objects inside it), for top-level +//! windows. Events about a child window are dropped; those of a window that no longer exists +//! by the time it is looked at are kept, which keeps its destruction. Events of the recorder's +//! own windows are not heard. The events of a window that arrive in a burst and say the same +//! thing each time (a state, location, name, description or value change) are folded into one +//! record per 100 ms ([`Coalescer`]); those records are `Debug` level and every other event is +//! `Info`. +//! - **Event Log**: from the System log, the warnings and errors (levels 1 to 3) of any provider, +//! and the `Microsoft-Windows-Kernel-Power`, `Microsoft-Windows-Kernel-PnP`, +//! `Microsoft-Windows-DxgKrnl`, `Display` and `Microsoft-Windows-Dwm-Core` providers at the +//! other levels. Only events logged after the recording started are heard. Windows' warning +//! level is written as `Error`, because the Mac's `messageType` has no warning. +//! +//! # What is not guaranteed +//! +//! - A burst's folded count is written on the next record for the same window and event. If none +//! follows, the events folded since the last record are counted nowhere in the file. +//! - The recorder does not list the windows that exist when it starts, so such a window appears +//! in `system.ndjson` only when something happens to it. +//! - The Event Log XML is read by searching its text, not parsed: entities such as `&` stay +//! as they are in the record. + +use crate::clock; +use crate::incidents::Draft; +use crate::sources::oslog::OsLogLevel; +use crate::sources::oslog::StreamInfo; +use crate::sources::oslog::StreamLive; +use crate::sources::oslog::StreamSpec; +use chrono::DateTime; +use chrono::Utc; +use color_eyre::eyre; +use parking_lot::Mutex; +use std::collections::HashMap; +use std::fs::File; +use std::io::BufWriter; +use std::io::Write; +use std::path::Path; +use std::sync::Arc; +use std::sync::atomic::AtomicU64; +use std::sync::atomic::Ordering; + +/// The `WinEvent` stream's file, relative to the session directory. It has the same name as the +/// `system` stream of the Mac's trace, and the same `oslog:system` source label. +pub const SYSTEM_FILE: &str = "oslog/system.ndjson"; +/// The Event Log stream's file, relative to the session directory. +pub const EVENT_LOG_FILE: &str = "oslog/eventlog.ndjson"; + +/// How long a window's repeated noisy events are folded into one. +const COALESCE_NS: u64 = 100_000_000; + +/// How many windows' last events are remembered before the oldest are forgotten. +const COALESCE_CAPACITY: usize = 4096; + +/// `EVENT_*` from winuser.h and oleacc.h, for the events komorebi and the shell care about. Any +/// other is named by its number. +const WIN_EVENTS: &[(u32, &str)] = &[ + (0x0001, "SystemSound"), + (0x0002, "SystemAlert"), + (0x0003, "SystemForeground"), + (0x0004, "SystemMenuStart"), + (0x0005, "SystemMenuEnd"), + (0x0006, "SystemMenuPopupStart"), + (0x0007, "SystemMenuPopupEnd"), + (0x0008, "SystemCaptureStart"), + (0x0009, "SystemCaptureEnd"), + (0x000A, "SystemMoveSizeStart"), + (0x000B, "SystemMoveSizeEnd"), + (0x000C, "SystemContextHelpStart"), + (0x000D, "SystemContextHelpEnd"), + (0x000E, "SystemDragDropStart"), + (0x000F, "SystemDragDropEnd"), + (0x0010, "SystemDialogStart"), + (0x0011, "SystemDialogEnd"), + (0x0012, "SystemScrollingStart"), + (0x0013, "SystemScrollingEnd"), + (0x0014, "SystemSwitchStart"), + (0x0015, "SystemSwitchEnd"), + (0x0016, "SystemMinimizeStart"), + (0x0017, "SystemMinimizeEnd"), + (0x8000, "ObjectCreate"), + (0x8001, "ObjectDestroy"), + (0x8002, "ObjectShow"), + (0x8003, "ObjectHide"), + (0x8004, "ObjectReorder"), + (0x8005, "ObjectFocus"), + (0x8006, "ObjectSelection"), + (0x800A, "ObjectStateChange"), + (0x800B, "ObjectLocationChange"), + (0x800C, "ObjectNameChange"), + (0x800D, "ObjectDescriptionChange"), + (0x800E, "ObjectValueChange"), + (0x800F, "ObjectParentChange"), + (0x8017, "ObjectCloaked"), + (0x8018, "ObjectUncloaked"), +]; + +/// Returns the name of a `WinEvent`: the `EVENT_*` constant of winuser.h and oleacc.h without its +/// prefix (`SystemForeground`, `ObjectShow`). +/// +/// Names are known for the events komorebi and the shell care about. Any other is named by its +/// number, `Event0x` and four hexadecimal digits. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::sources::wintrace::win_event_name; +/// +/// assert_eq!(win_event_name(0x0003), "SystemForeground"); +/// assert_eq!(win_event_name(0x8017), "ObjectCloaked"); +/// assert_eq!(win_event_name(0x7777), "Event0x7777"); +/// ``` +#[must_use] +pub fn win_event_name(code: u32) -> String { + WIN_EVENTS + .iter() + .find(|(number, _)| *number == code) + .map_or_else( + || format!("Event0x{code:04X}"), + |(_, name)| (*name).to_string(), + ) +} + +/// Returns `true` if and only if the `WinEvent` arrives in bursts and says the same thing each +/// time. +/// +/// These are the object state, location, name, description and value changes (`0x800A` to +/// `0x800E`), which a window that is being dragged, resized or redrawn sends in bursts. A +/// [`Coalescer`] folds them, and the records written for them are `Debug` level. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::sources::wintrace::{is_noisy, win_event_name}; +/// +/// assert!(is_noisy(0x800B), "{}", win_event_name(0x800B)); // ObjectLocationChange +/// assert!(!is_noisy(0x8002), "{}", win_event_name(0x8002)); // ObjectShow +/// ``` +#[must_use] +pub fn is_noisy(code: u32) -> bool { + // state, location, name, description and value changes + matches!(code, 0x800A..=0x800E) +} + +/// What to do with one more of a window's events, as [`Coalescer::offer`] decides. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Offer { + /// Record it, saying how many like it were folded into it since the last one recorded. + Emit { + /// How many events of the same window and kind were folded since the last one recorded. + /// `0` for an event that was not part of a burst. + folded: u32, + }, + /// It is one of a burst: counted, not recorded. + Fold, +} + +/// Folds a window's repeated noisy events into one record per 100 ms. +/// +/// This keeps dragging a window from writing a record per pixel. An event that is not noisy +/// ([`is_noisy`]) is never folded: a window shown, hidden, focused or destroyed is always its own +/// record. +/// +/// A window and a kind of event are folded separately: a burst of location changes of one window +/// does not fold its name changes, or another window's location changes. The memory is bounded: it +/// holds at most 4096 pairs of a window and a kind, and when that fills it forgets the pairs not +/// heard from in the last second, and all of them if that is not enough. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::sources::wintrace::{Coalescer, Offer}; +/// +/// let mut coalescer = Coalescer::default(); +/// let (window, moved) = (0x1234, 0x800B); // ObjectLocationChange +/// +/// // the first of a burst is recorded, the rest within 100 ms are folded +/// assert_eq!(coalescer.offer(1_000_000_000, window, moved), Offer::Emit { folded: 0 }); +/// for step in 1..=5 { +/// assert_eq!(coalescer.offer(1_000_000_000 + step * 10_000_000, window, moved), Offer::Fold); +/// } +/// +/// // the next one after the burst is recorded, and says how many were folded before it +/// assert_eq!(coalescer.offer(1_300_000_000, window, moved), Offer::Emit { folded: 5 }); +/// +/// // a window shown (0x8002) is never folded, however fast +/// assert_eq!(coalescer.offer(1_300_000_001, window, 0x8002), Offer::Emit { folded: 0 }); +/// assert_eq!(coalescer.offer(1_300_000_002, window, 0x8002), Offer::Emit { folded: 0 }); +/// ``` +#[derive(Debug, Default)] +pub struct Coalescer { + last: HashMap<(isize, u32), (u64, u32)>, +} + +impl Coalescer { + /// Decides what to do with an event of `window` of kind `code` (a `WinEvent` number) heard at + /// `now_ns`, on the master clock. + /// + /// A noisy event ([`is_noisy`]) is folded if the last one of the same window and kind that was + /// recorded was less than 100 ms before `now_ns`, and otherwise recorded with the number + /// folded since. Any other event is recorded with `0` folded. + pub fn offer(&mut self, now_ns: u64, window: isize, code: u32) -> Offer { + if !is_noisy(code) { + return Offer::Emit { folded: 0 }; + } + + if self.last.len() >= COALESCE_CAPACITY { + // a long-running recording has seen many windows come and go + self.last + .retain(|_, (at, _)| now_ns.saturating_sub(*at) < 10 * COALESCE_NS); + if self.last.len() >= COALESCE_CAPACITY { + self.last.clear(); + } + } + + let entry = self.last.entry((window, code)).or_insert((0, 0)); + if entry.0 != 0 && now_ns.saturating_sub(entry.0) < COALESCE_NS { + entry.1 += 1; + return Offer::Fold; + } + + let folded = std::mem::take(&mut entry.1); + entry.0 = now_ns; + Offer::Emit { folded } + } +} + +/// One record of the OS trace, as it is written: [`to_line`](TraceRecord::to_line) gives its line +/// of the NDJSON file. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct TraceRecord { + /// The time on the master clock, in nanoseconds. + pub host_ns: u64, + /// The wall-clock time, in microseconds since the Unix epoch. + pub wall_us: i64, + /// The process of the window (`WinEvent`) or of the logger (Event Log); `0` if unknown. + pub pid: i64, + /// The program, e.g. `chrome.exe`; empty if it could not be found. + pub process: String, + /// `winevent` or the Event Log provider. + pub subsystem: String, + /// The `WinEvent`'s name, or the Event Log event id. + pub category: String, + /// `Debug`, `Info`, `Error`, `Fault`: the names the Mac's records use. + pub level: &'static str, + /// The text of the record: ` hwnd=0x class=` for a `WinEvent`, or the + /// provider, event id and data for an Event Log record. + pub message: String, +} + +/// `2026-10-27 12:34:56.123456+0000`: the shape the Mac's records carry, which is what the readers +/// pick the time of day out of. +fn timestamp(wall_us: i64) -> String { + DateTime::::from_timestamp_micros(wall_us) + .map(|time| time.format("%Y-%m-%d %H:%M:%S%.6f%z").to_string()) + .unwrap_or_default() +} + +impl TraceRecord { + /// Returns the record as a line of the NDJSON file, without a line terminator. The field names + /// are the Mac's unified log's, so the readers of that need no second path, with `hostNs` + /// where the Mac has a tick count: the time is on the master clock already, whichever OS wrote + /// it. + /// + /// The keys are `hostNs`, `timestamp` (from `wall_us`, as `2026-10-26 12:00:00.123456+0000`), + /// `processID`, `processImagePath`, `subsystem`, `category`, `messageType` and `eventMessage`. + /// A line reads back as an [`OsLogRecord`](crate::sources::oslog::OsLogRecord). + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::sources::oslog::OsLogRecord; + /// use komorebi_recorder::sources::wintrace::TraceRecord; + /// + /// let record = TraceRecord { + /// host_ns: 5_000_000_000, + /// wall_us: 1_793_016_000_123_456, + /// pid: 4242, + /// process: "chrome.exe".to_string(), + /// subsystem: "winevent".to_string(), + /// category: "ObjectShow".to_string(), + /// level: "Info", + /// message: "ObjectShow hwnd=0x1f2a class=Chrome_WidgetWin_1".to_string(), + /// }; + /// + /// assert_eq!( + /// record.to_line(), + /// r#"{"category":"ObjectShow","eventMessage":"ObjectShow hwnd=0x1f2a class=Chrome_WidgetWin_1","hostNs":5000000000,"messageType":"Info","processID":4242,"processImagePath":"chrome.exe","subsystem":"winevent","timestamp":"2026-10-26 12:00:00.123456+0000"}"# + /// ); + /// + /// // the readers of the Mac's trace read it + /// let read = OsLogRecord::parse(&record.to_line()).ok_or("not a record")?; + /// assert_eq!((read.pid, read.host_ns), (4242, Some(5_000_000_000))); + /// # Ok::<(), Box>(()) + /// ``` + #[must_use] + pub fn to_line(&self) -> String { + serde_json::json!({ + "hostNs": self.host_ns, + "timestamp": timestamp(self.wall_us), + "processID": self.pid, + "processImagePath": self.process, + "subsystem": self.subsystem, + "category": self.category, + "messageType": self.level, + "eventMessage": self.message, + }) + .to_string() + } +} + +/// What an Event Log record says, from its XML ([`summarize_event_xml`]). +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct EventLogSummary { + /// The provider's name (`Microsoft-Windows-Kernel-Power`). + pub provider: String, + /// The event id, as the text of the record's `EventID` element (`506`). + pub event_id: String, + /// `Fault` for Windows level 1 (critical), `Error` for 2 (error) and 3 (warning), `Info` for + /// every other level. + pub level: &'static str, + /// The process that logged it, where the record says. + pub pid: Option, + /// The record's data, `name=value` where it is named. + pub data: Vec, +} + +/// The text between `` and ``, the first time it appears. +fn element<'a>(xml: &'a str, tag: &str) -> Option<&'a str> { + let open = xml.find(&format!("<{tag}"))?; + let start = xml[open..].find('>')? + open + 1; + let end = xml[start..].find(&format!(""))? + start; + Some(&xml[start..end]) +} + +/// An attribute's value, in single or double quotes. +fn attribute<'a>(xml: &'a str, name: &str) -> Option<&'a str> { + for quote in ['\'', '"'] { + let key = format!("{name}={quote}"); + if let Some(at) = xml.find(&key) { + let start = at + key.len(); + let end = xml[start..].find(quote)? + start; + return Some(&xml[start..end]); + } + } + + None +} + +/// Reads what matters out of an Event Log record's XML without an XML parser: the provider, the +/// event id, the level, and the data it carries. +/// +/// The text is searched, not parsed, so it is right for the XML Windows renders for an event +/// (attributes in single or double quotes) and does not decode entities. The data is each `Data` +/// element's trimmed text, as `name=value` when the element has a `Name` attribute; an empty one +/// is left out. The process is the `ProcessID` of the `Execution` element. +/// +/// Returns `None` if the text has no `Provider` with a `Name`, or no `EventID`. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::sources::wintrace::summarize_event_xml; +/// +/// let xml = "\ +/// \ +/// 5064\ +/// 3 entering plain"; +/// +/// let summary = summarize_event_xml(xml).ok_or("not an event")?; +/// assert_eq!(summary.provider, "Microsoft-Windows-Kernel-Power"); +/// assert_eq!(summary.event_id, "506"); +/// assert_eq!(summary.level, "Info"); +/// assert_eq!(summary.pid, Some(4)); +/// assert_eq!(summary.data, ["Reason=3", "Detail=entering", "plain"]); +/// +/// // an error stays an error, and something that is not an event is nothing +/// let error = xml.replace("4", "2"); +/// assert_eq!(summarize_event_xml(&error).map(|summary| summary.level), Some("Error")); +/// assert_eq!(summarize_event_xml("not xml"), None); +/// # Ok::<(), Box>(()) +/// ``` +#[must_use] +pub fn summarize_event_xml(xml: &str) -> Option { + let provider_tag = &xml[xml.find("').next()?, "Name")?.to_string(); + let event_id = element(xml, "EventID")?.trim().to_string(); + // 1 critical, 2 error, 3 warning, 4 information, 5 verbose (0: no level, which is information) + let level = match element(xml, "Level").map(str::trim) { + Some("1") => "Fault", + Some("2") => "Error", + Some("3") => "Error", + _ => "Info", + }; + + let mut data = Vec::new(); + let mut rest = xml; + while let Some(at) = rest.find("') else { break }; + let tag = &rest[..close]; + let name = attribute(tag, "Name"); + // `` has no text + if tag.ends_with('/') { + rest = &rest[close..]; + continue; + } + + let Some(end) = rest[close..].find("") else { + break; + }; + let value = rest[close + 1..close + end].trim(); + if !value.is_empty() { + data.push(match name { + Some(name) => format!("{name}={value}"), + None => value.to_string(), + }); + } + rest = &rest[close + end..]; + } + + let pid = xml + .find("').next()?, "ProcessID")) + .and_then(|pid| pid.parse().ok()); + + Some(EventLogSummary { + provider, + event_id, + level, + pid, + data, + }) +} + +#[derive(Debug, Default)] +struct Counters { + lines: AtomicU64, + bytes: AtomicU64, + first_ns: AtomicU64, + last_ns: AtomicU64, +} + +/// One file of the OS trace, written to by whichever thread hears something. +/// +/// A stream writes its records as NDJSON lines ([`TraceRecord::to_line`]) through a buffered +/// writer behind a lock, and counts what it writes for the manifest. It can be shared between +/// threads (it is handed out in an [`Arc`]). Written lines are visible to other readers only after +/// [`flush`](TraceStream::flush); [`TraceSet::checkpoint`] does that. +/// +/// A stream needs a directory to write into, so it has no doctest. It is covered by +/// `a_stream_counts_what_it_writes_and_reports_it_for_the_manifest` in this file's unit tests. +pub struct TraceStream { + spec: StreamSpec, + started_ns: u64, + out: Mutex>, + counters: Counters, +} + +impl TraceStream { + /// Creates the stream's file `file` under `dir` (and `dir/oslog`), truncating it if it exists. + /// + /// `name` and `source` are what the manifest records for the stream (see + /// [`StreamSpec`]): for example `winevents` and `oslog:system`. The stream has no predicate and + /// follows no single process. + /// + /// # Errors + /// + /// Returns an error if `dir/oslog` or the file cannot be created. + pub fn create(dir: &Path, name: &str, source: &str, file: &str) -> eyre::Result> { + std::fs::create_dir_all(dir.join("oslog"))?; + Ok(Arc::new(Self { + spec: StreamSpec { + name: name.to_string(), + source: source.to_string(), + predicate: String::new(), + level: OsLogLevel::Debug, + file: file.to_string(), + pid: None, + }, + started_ns: clock::mono_now_ns(), + out: Mutex::new(BufWriter::new(File::create(dir.join(file))?)), + counters: Counters::default(), + })) + } + + /// Appends `record` as one line and counts it. + /// + /// A failed write is dropped and not counted: it must not take the recording down, and the + /// counters say what was kept. + pub fn write(&self, record: &TraceRecord) { + let line = record.to_line(); + let mut out = self.out.lock(); + // a failed write must not take the recording down; the counters say what was kept + if writeln!(out, "{line}").is_err() { + return; + } + + self.counters.lines.fetch_add(1, Ordering::Relaxed); + self.counters + .bytes + .fetch_add(line.len() as u64 + 1, Ordering::Relaxed); + let _ = self.counters.first_ns.compare_exchange( + 0, + record.host_ns, + Ordering::Relaxed, + Ordering::Relaxed, + ); + self.counters + .last_ns + .store(record.host_ns, Ordering::Relaxed); + } + + /// Make what has been written readable from outside: for the manifest checkpoints, so a + /// recording killed now can still be recovered with what this holds. + pub fn flush(&self) { + let _ = self.out.lock().flush(); + } + + /// Returns the live counters of the stream, for the display. + #[must_use] + pub fn live(&self) -> StreamLive { + StreamLive { + name: self.spec.name.clone(), + events: self.counters.lines.load(Ordering::Relaxed), + bytes: self.counters.bytes.load(Ordering::Relaxed), + } + } + + /// Returns the stream as the manifest records it. `header` says what the stream is, in words, + /// and `error` is why it is not what was asked for, if it is not. + /// + /// The stream counts as ready from the moment it was created: `spawned_mach_ns` and + /// `ready_mach_ns` are that time, and `restarts` is `0`. `first_event_mach_ns` and + /// `last_event_mach_ns` are the `host_ns` of the first and last record written, `None` if none + /// was. + #[must_use] + pub fn info(&self, header: &str, error: Option) -> StreamInfo { + let nonzero = |value: u64| (value != 0).then_some(value); + StreamInfo { + spec: self.spec.clone(), + spawned_mach_ns: self.started_ns, + ready_mach_ns: Some(self.started_ns), + header: Some(header.to_string()), + events: self.counters.lines.load(Ordering::Relaxed), + bytes: self.counters.bytes.load(Ordering::Relaxed), + first_event_mach_ns: nonzero(self.counters.first_ns.load(Ordering::Relaxed)), + last_event_mach_ns: nonzero(self.counters.last_ns.load(Ordering::Relaxed)), + restarts: 0, + error, + } + } +} + +/// The two files of the Windows OS trace and the taps that fill them. +/// +/// A set creates both files, starts the taps of the host ([`crate::platform::trace::start`]: on +/// Windows a `WinEvent` hook and two Event Log subscriptions, on any other host nothing) and +/// reports each stream to the manifest. The recorder creates one on a host that has an OS trace but +/// no `log stream`. +/// +/// A tap that cannot start does not stop the recording: the other carries on, the reason is in +/// [`problems`](TraceSet::problems), and [`drafts`](TraceSet::drafts) turns it into incidents. +/// +/// Starting a set needs a directory and, for the taps, Windows, so there is no doctest. The record +/// format, the folding, the XML reading and the stream counters it is built from are covered by the +/// unit tests of this file; the taps are covered by none, and are checked on a real machine (see +/// `docs/dev/windows-checkpoints.md`). +pub struct TraceSet { + /// The `WinEvent` stream: `oslog/system.ndjson`, named `winevents` in the manifest. + pub system: Arc, + /// The Event Log stream: `oslog/eventlog.ndjson`, named `eventlog` in the manifest. + pub event_log: Arc, + /// Why a tap could not be started, in words; the recording goes on without it. + problems: Vec, + taps: Option, +} + +impl TraceSet { + /// Creates the files and starts listening. A tap that cannot start is reported in + /// [`TraceSet::problems`] and the other carries on. + /// + /// # Errors + /// + /// 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 (taps, problems) = crate::platform::trace::start(system.clone(), event_log.clone()); + Ok(Self { + system, + event_log, + problems, + taps, + }) + } + + /// Returns why a tap could not be started, in words, one entry for each: they begin with + /// `winevents` or `eventlog`, naming the tap. Empty when both started. + #[must_use] + pub fn problems(&self) -> &[String] { + &self.problems + } + + /// Returns the live counters of the two streams, the `WinEvent` one first. + #[must_use] + pub fn snapshot(&self) -> Vec { + vec![self.system.live(), self.event_log.live()] + } + + fn infos(&self) -> Vec { + let error = |name: &str| { + self.problems + .iter() + .find(|problem| problem.starts_with(name)) + .cloned() + }; + vec![ + self.system.info( + "WinEvent hook on every top-level window", + error("winevents"), + ), + self.event_log.info( + "System Event Log: warnings, errors, display and power providers", + error("eventlog"), + ), + ] + } + + /// Flushes both files and returns the streams' state so far, the `WinEvent` one first, for a + /// manifest checkpoint. A stream whose tap could not start carries the reason as its `error`. + #[must_use] + pub fn checkpoint(&self) -> Vec { + self.system.flush(); + self.event_log.flush(); + self.infos() + } + + /// Stops listening, flushes both files and reports what each stream held. Nothing is heard + /// after this returns. + pub fn stop(&mut self) -> Vec { + // dropping the taps unhooks them: nothing arrives after this + self.taps = None; + self.checkpoint() + } + + /// Returns a [`kind::LOG_STREAM_LOST`](crate::incidents::kind::LOG_STREAM_LOST) incident for + /// each problem (`the OS trace is incomplete: `), for the incident log. Empty when both + /// taps started. + #[must_use] + pub fn drafts(&self) -> Vec { + self.problems + .iter() + .map(|problem| { + Draft::new( + crate::incidents::kind::LOG_STREAM_LOST, + format!("the OS trace is incomplete: {problem}"), + ) + }) + .collect() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn win_events_are_named_and_unknown_ones_are_numbered() { + assert_eq!(win_event_name(0x0003), "SystemForeground"); + assert_eq!(win_event_name(0x800B), "ObjectLocationChange"); + assert_eq!(win_event_name(0x8017), "ObjectCloaked"); + assert_eq!(win_event_name(0x7777), "Event0x7777"); + } + + #[test] + fn a_burst_for_one_window_is_one_record_that_says_how_many_it_stands_for() { + let mut coalescer = Coalescer::default(); + let moved = 0x800B; + let window = 0x1234; + + assert_eq!( + coalescer.offer(1_000_000_000, window, moved), + Offer::Emit { folded: 0 } + ); + for step in 1..=5 { + assert_eq!( + coalescer.offer(1_000_000_000 + step * 10_000_000, window, moved), + Offer::Fold + ); + } + + // the burst is over: the next one is recorded and says how many were folded before it + assert_eq!( + coalescer.offer(1_300_000_000, window, moved), + Offer::Emit { folded: 5 } + ); + } + + #[test] + fn windows_and_events_are_folded_separately_and_only_noisy_ones_at_all() { + let mut coalescer = Coalescer::default(); + assert_eq!(coalescer.offer(1, 1, 0x800B), Offer::Emit { folded: 0 }); + // another window, and another kind of event, are their own + assert_eq!(coalescer.offer(2, 2, 0x800B), Offer::Emit { folded: 0 }); + assert_eq!(coalescer.offer(3, 1, 0x800C), Offer::Emit { folded: 0 }); + + // a window shown or hidden or focused is always its own record, however fast + for _ in 0..3 { + assert_eq!(coalescer.offer(4, 1, 0x8002), Offer::Emit { folded: 0 }); + assert_eq!(coalescer.offer(4, 1, 0x0003), Offer::Emit { folded: 0 }); + } + } + + #[test] + fn the_memory_of_windows_is_bounded() { + let mut coalescer = Coalescer::default(); + for window in 0..(COALESCE_CAPACITY as isize * 3) { + coalescer.offer(1_000_000_000, window, 0x800B); + } + assert!(coalescer.last.len() <= COALESCE_CAPACITY); + } + + #[test] + fn a_record_is_a_line_the_existing_readers_understand() { + let record = TraceRecord { + host_ns: 5_000_000_000, + wall_us: 1_793_016_000_123_456, + pid: 4242, + process: "chrome.exe".to_string(), + subsystem: "winevent".to_string(), + category: "ObjectLocationChange".to_string(), + level: "Info", + message: "hwnd=0x1f2a class=Chrome_WidgetWin_1 (+3 folded)".to_string(), + }; + + let parsed = crate::sources::oslog::OsLogRecord::parse(&record.to_line()) + .expect("the Mac's reader parses it"); + assert_eq!(parsed.pid, 4242); + assert_eq!(parsed.process_name(), "chrome.exe"); + assert_eq!(parsed.subsystem, "winevent"); + assert_eq!(parsed.category, "ObjectLocationChange"); + assert_eq!(parsed.host_ns, Some(5_000_000_000)); + assert!(parsed.timestamp.starts_with("2026-10-26 12:00:00.123456")); + assert_eq!( + crate::sources::oslog::extract_time_ns( + record.to_line().as_bytes(), + crate::clock::Timebase { numer: 1, denom: 1 } + ), + Some(5_000_000_000) + ); + } + + const EVENT_XML: &str = "\ + \ + 5064\ + 3 entering plain"; + + #[test] + fn an_event_log_record_is_read_for_its_provider_id_level_and_data() { + let summary = summarize_event_xml(EVENT_XML).expect("summary"); + assert_eq!(summary.provider, "Microsoft-Windows-Kernel-Power"); + assert_eq!(summary.event_id, "506"); + assert_eq!(summary.level, "Info"); + assert_eq!(summary.pid, Some(4)); + assert_eq!(summary.data, ["Reason=3", "Detail=entering", "plain"]); + } + + #[test] + fn errors_and_faults_keep_their_severity_and_junk_is_not_a_record() { + let error = EVENT_XML.replace("4", "2"); + assert_eq!(summarize_event_xml(&error).expect("summary").level, "Error"); + let critical = EVENT_XML.replace("4", "1"); + assert_eq!( + summarize_event_xml(&critical).expect("summary").level, + "Fault" + ); + assert_eq!(summarize_event_xml("not xml"), None); + } + + #[test] + fn a_stream_counts_what_it_writes_and_reports_it_for_the_manifest() { + let dir = std::env::temp_dir().join(format!("komorebi-wintrace-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + let stream = + TraceStream::create(&dir, "winevents", "oslog:system", SYSTEM_FILE).expect("create"); + + for host_ns in [10, 30] { + stream.write(&TraceRecord { + host_ns, + wall_us: 1, + pid: 1, + process: "a.exe".to_string(), + subsystem: "winevent".to_string(), + category: "ObjectShow".to_string(), + level: "Info", + message: "hwnd=0x1".to_string(), + }); + } + stream.flush(); + + let info = stream.info("hook", None); + assert_eq!( + ( + info.events, + info.first_event_mach_ns, + info.last_event_mach_ns + ), + (2, Some(10), Some(30)) + ); + assert_eq!(info.spec.source, "oslog:system"); + let text = std::fs::read_to_string(dir.join(SYSTEM_FILE)).expect("file"); + assert_eq!(text.lines().count(), 2); + assert_eq!(stream.live().events, 2); + let _ = std::fs::remove_dir_all(&dir); + } +}