feat(sources): the OS trace

What the OS says while komorebi acts: the unified log (`log stream`) on macOS,
one file per managed application, komorebi's process and the system; on Windows
the WinEvents komorebi hears, folded when repeated, and the Event Log's warnings
and its display, power and GPU providers. Both end up as `oslog/*.ndjson` on the
master clock, and a host with no OS trace says so instead of failing.
This commit is contained in:
LGUG2Z committed 2026-10-27 22:22:56 -07:00
1 parent 4724d831ba
commit 9d35869f88
15 files changed
+2784

No files matched your search

Generated
+54
View File
@@ -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"
+10
View File
@@ -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",
+1
View File
@@ -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
+11
View File
@@ -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/<exe>-<pid>.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 | `<private>` 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
+1
View File
@@ -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 }
@@ -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.)
@@ -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<TraceStream>,
_event_log: Arc<TraceStream>,
) -> (Option<Taps>, Vec<String>) {
(
None,
vec!["winevents: this host records its OS trace another way".to_string()],
)
}
+9
View File
@@ -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.
@@ -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<TraceStream>,
_event_log: Arc<TraceStream>,
) -> (Option<Taps>, Vec<String>) {
(
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;
@@ -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
+441
View File
@@ -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<Mutex<Option<Sender<Heard>>>> = 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<Heard>, 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<i64, String> = 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<Result<u32, String>>) {
// 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<TraceStream>` 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<String> {
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::<TraceStream>().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<TraceStream>, query: &str) -> Result<Subscription, String> {
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<JoinHandle<()>>,
subscriptions: Vec<Subscription>,
}
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<TraceStream>, event_log: Arc<TraceStream>) -> (Option<Taps>, Vec<String>) {
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)
}
+4
View File
@@ -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<u64>,
/// The byte ranges of komorebi's log that were recorded, which together make `komorebi.log`.
pub log_segments: Vec<LogSegment>,
/// The OS trace streams that were recorded, one per file under `oslog/`.
pub oslog: Vec<StreamInfo>,
/// The applications that own windows komorebi manages, which each get an OS trace stream of their own on a Mac.
pub apps: Vec<AppRecord>,
/// 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(),
+4
View File
@@ -11,6 +11,8 @@
//! |---|---|---|
//! | [`komorebi_events`] | `events.jsonl` (one JSON object per line), `states/<id>.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;
File diff suppressed because it is too large. Load diff
+859
View File
@@ -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` | `<name> hwnd=0x<handle> class=<window class>` for a `WinEvent`; `<provider> event <id>: <data>` 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 `&amp;` 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: `<name> hwnd=0x<handle> class=<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::<Utc>::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<dyn std::error::Error>>(())
/// ```
#[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<i64>,
/// The record's data, `name=value` where it is named.
pub data: Vec<String>,
}
/// The text between `<tag ...>` and `</tag>`, 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!("</{tag}>"))? + 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 = "<Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'>\
/// <System><Provider Name='Microsoft-Windows-Kernel-Power' Guid='{331C3B3A-2005-44C2-AC5E-77220C37D6B4}'/>\
/// <EventID>506</EventID><Level>4</Level><Execution ProcessID='4' ThreadID='8'/></System>\
/// <EventData><Data Name='Reason'>3</Data><Data Name='Detail'> entering </Data><Data/><Data>plain</Data></EventData></Event>";
///
/// 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("<Level>4</Level>", "<Level>2</Level>");
/// assert_eq!(summarize_event_xml(&error).map(|summary| summary.level), Some("Error"));
/// assert_eq!(summarize_event_xml("not xml"), None);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn summarize_event_xml(xml: &str) -> Option<EventLogSummary> {
let provider_tag = &xml[xml.find("<Provider")?..];
let provider = attribute(provider_tag.split('>').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("<Data") {
rest = &rest[at..];
let Some(close) = rest.find('>') else { break };
let tag = &rest[..close];
let name = attribute(tag, "Name");
// `<Data/>` has no text
if tag.ends_with('/') {
rest = &rest[close..];
continue;
}
let Some(end) = rest[close..].find("</Data>") 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("<Execution")
.and_then(|at| attribute(xml[at..].split('>').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<BufWriter<File>>,
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<Arc<Self>> {
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<String>) -> 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<TraceStream>,
/// The Event Log stream: `oslog/eventlog.ndjson`, named `eventlog` in the manifest.
pub event_log: Arc<TraceStream>,
/// Why a tap could not be started, in words; the recording goes on without it.
problems: Vec<String>,
taps: Option<crate::platform::trace::Taps>,
}
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<Self> {
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<StreamLive> {
vec![self.system.live(), self.event_log.live()]
}
fn infos(&self) -> Vec<StreamInfo> {
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<StreamInfo> {
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<StreamInfo> {
// 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: <problem>`), for the incident log. Empty when both
/// taps started.
#[must_use]
pub fn drafts(&self) -> Vec<Draft> {
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 = "<Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'>\
<System><Provider Name='Microsoft-Windows-Kernel-Power' Guid='{331C3B3A-2005-44C2-AC5E-77220C37D6B4}'/>\
<EventID>506</EventID><Level>4</Level><TimeCreated SystemTime='2026-10-27T12:00:00.000000000Z'/><Execution ProcessID='4' ThreadID='8'/></System>\
<EventData><Data Name='Reason'>3</Data><Data Name='Detail'> entering </Data><Data/><Data>plain</Data></EventData></Event>";
#[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("<Level>4</Level>", "<Level>2</Level>");
assert_eq!(summarize_event_xml(&error).expect("summary").level, "Error");
let critical = EVENT_XML.replace("<Level>4</Level>", "<Level>1</Level>");
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);
}
}