mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-18 14:48:34 +01:00
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:
1 parent
4724d831ba
commit
9d35869f88
15 files changed
+2784
No files matched your search
Generated
+54
@@ -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"
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,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
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
@@ -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(),
|
||||
|
||||
@@ -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
@@ -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 `&` 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);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user