From af6e332fedae25331406aef4343436791722cba0 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Tue, 27 Oct 2026 06:14:52 -0700 Subject: [PATCH] feat(analysis): read komorebi's log as handlers komorebi's log says what happened but not which handler was running. The log is parsed into lines with their span chain, and a handler's lines are gathered into one block, from the line that opens it to the one that ends it, as each flavor's log marks them: komorebi for Mac logs a header, komorebi for Windows has none and a block is found from its span. --- komorebi-recorder/src/analysis/blocks.rs | 817 ++++++++++++++++++ komorebi-recorder/src/analysis/flavor/mac.rs | 49 ++ komorebi-recorder/src/analysis/flavor/mod.rs | 70 +- .../src/analysis/flavor/windows.rs | 69 ++ komorebi-recorder/src/analysis/logparse.rs | 618 +++++++++++++ komorebi-recorder/src/analysis/mod.rs | 2 + .../fixtures/komorebi_plaintext_sample.log | 55 ++ 7 files changed, 1678 insertions(+), 2 deletions(-) create mode 100644 komorebi-recorder/src/analysis/blocks.rs create mode 100644 komorebi-recorder/src/analysis/logparse.rs create mode 100644 komorebi-recorder/tests/fixtures/komorebi_plaintext_sample.log diff --git a/komorebi-recorder/src/analysis/blocks.rs b/komorebi-recorder/src/analysis/blocks.rs new file mode 100644 index 00000000..666dfe9b --- /dev/null +++ b/komorebi-recorder/src/analysis/blocks.rs @@ -0,0 +1,817 @@ +//! Which lines of komorebi's log belong to which event. +//! +//! komorebi handles one event or command at a time, under one lock, and everything it logs while +//! doing so carries the handler's span (`process_event:` or `process_command:`). That makes a +//! handler's output recoverable as a **block**: the header line (`processing event: ...`) and the +//! lines after it that share the span. Lines logged from other threads (the border manager, the +//! reaper, the reconcilers) carry no handler span; they are *ambient* and can only be related to a +//! handler by when they happened. +//! +//! Subscriber notifications are sent *after* the handler body, so an event's receive time marks the +//! **end** of its handler, not its start. [`pair`] ties each recorded event to the block that +//! produced it, and records how sure it is: +//! +//! - [`Quality::Pushed`]: komorebi logged `pushed notification to subscriber: ` (a DEBUG line) +//! just before sending, which is exact. +//! - [`Quality::Header`]: matched by name, process and notification to the last header before the +//! event was received, after the previous event. +//! - [`Quality::None`]: no block found. Events whose header is only logged at TRACE (the manual +//! `Show` hacks) are like this, as are events recorded while komorebi's log was off. +//! +//! What cannot be known from the log is when komorebi *dequeued* the event: the time spent waiting +//! for the lock or for the accessibility calls made before the header is invisible. +//! +//! Where a block starts and ends depends on the komorebi that wrote the log, so the [`Rules`] of +//! its flavor decide: komorebi for Mac logs a header line, and komorebi for Windows is recognized +//! by the fields of the span its lines carry (see [`Rules::block_header`] and +//! [`Rules::is_block_end`]). This module is the same for both: [`build`] groups the lines, and +//! [`pair`] ties events to the groups. +//! +//! # Example +//! +//! ```rust +//! use komorebi_recorder::analysis::blocks::{BlockKind, build}; +//! use komorebi_recorder::analysis::flavor::Flavor; +//! use komorebi_recorder::analysis::logparse; +//! use komorebi_recorder::clock::{Anchor, ClockMap}; +//! +//! let log = "\ +//! 2026-10-26T23:09:16.100000Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 10 with notification AXWindowMoved +//! 2026-10-26T23:09:16.150000Z INFO komorebi::border_manager: invalidating border observer +//! 2026-10-26T23:09:16.200000Z WARN process_event:update_focused_workspace: komorebi::workspace: failed to set window position: AXError::InvalidUIElement +//! 2026-10-26T23:09:17.000000Z INFO process_event: komorebi::process_event: processing event: FocusChange for process 11 with notification AXApplicationActivated +//! "; +//! let lines = logparse::parse(log.as_bytes()); +//! +//! // the log's wall clock and the master clock, at two anchors a minute apart +//! let wall_us = chrono::DateTime::parse_from_rfc3339("2026-10-26T23:09:16Z")?.timestamp_micros(); +//! let clock = ClockMap::new(vec![ +//! Anchor { mach_ns: 1_000_000_000, wall_us }, +//! Anchor { mach_ns: 61_000_000_000, wall_us: wall_us + 60_000_000 }, +//! ]); +//! +//! let blocks = build(&lines, &clock, Flavor::Macos.rules()); +//! assert_eq!(blocks.len(), 2); +//! +//! let first = &blocks[0]; +//! assert_eq!(first.kind, BlockKind::Event); +//! assert_eq!(first.name, "MoveEnd"); +//! assert_eq!(first.pid, Some(10)); +//! // the border manager's line 2 has no handler span: it is ambient, in no block +//! assert_eq!(first.lines, [1, 3]); +//! assert_eq!(first.warnings, 1); +//! assert!((first.logged_ms() - 100.0).abs() < 1.0); +//! # Ok::<(), Box>(()) +//! ``` + +use super::events::EventRecord; +use super::events::Family; +use super::flavor::BlockHeader; +use super::flavor::Rules; +use super::logparse::Level; +use super::logparse::Line; +use crate::clock::ClockMap; +use schemars::JsonSchema; +use serde::Serialize; +use std::collections::BTreeMap; + +/// The kind of thing a handler was handling: an event from the OS or a command. +/// +/// Serialized in kebab case (`event`, `command`). The two are told apart by the root span of the +/// handler's lines: `process_event` or `process_command`. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, JsonSchema)] +#[serde(rename_all = "kebab-case")] +pub enum BlockKind { + /// The handler of an event the OS reported (`process_event`). + Event, + /// The handler of a command from `komorebic` or a hotkey daemon (`process_command`). + Command, +} + +/// A line komorebi logged when it handed a notification to a subscriber. +/// +/// komorebi logs it at DEBUG, as `pushed notification to subscriber: `, just before it sends. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)] +pub struct Push { + /// The subscriber's name, as registered with komorebi. + pub subscriber: String, + /// The line's number in `komorebi.log`, counting from 1. + pub line: u64, + /// When the line was logged, in nanoseconds on the host's master monotonic clock (`mach_` is a + /// historical spelling). + pub mach_ns: u64, +} + +/// One handler's lines of komorebi's log: its header and the lines after it that share its span. +/// +/// Built by [`build`]. A block starts at the header line the flavor's rules recognize and goes on +/// while lines carry the handler's root span of the same kind, until the rules say it finished or +/// the next header starts another. Times are nanoseconds on the host's master monotonic clock +/// (`mach_` is a historical spelling), mapped from the log's wall-clock times through the +/// session's clock anchors. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct Block { + /// The block's position in the list [`build`] returned, counting from 0. [`Pair::block`] names + /// a block by it. + pub id: usize, + /// Whether the handler was handling an event or a command. + pub kind: BlockKind, + /// `MoveEnd`, `FocusWorkspaceNumber`, ... + pub name: String, + /// The process the event was about, where the log gives one (komorebi for Mac does). + pub pid: Option, + /// The window the event was about, where komorebi's log gives one (komorebi for Windows does). + #[serde(default, skip_serializing_if = "Option::is_none")] + pub window_id: Option, + /// The notification the OS reported, e.g. `AXWindowMoved`, where the log gives it; `None` for a + /// command. + pub notification: Option, + /// The number of the header line in `komorebi.log`, counting from 1. + pub header_line: u64, + /// When the header was logged: the earliest known moment of the handler. + pub header_mach_ns: u64, + /// The number of the last line of the block in `komorebi.log`. + pub last_line: u64, + /// When the handler's last line was logged. + pub end_mach_ns: u64, + /// Line numbers of everything the handler logged, header first. + pub lines: Vec, + /// The line saying the handler finished, for the flavors whose log has one (`processed command:` + /// on a Mac, for commands only; `processed` and `processed: ` on Windows). + pub finished_line: Option, + /// The lines in which komorebi handed a notification to a subscriber, in order. + pub pushes: Vec, + /// How many lines of the block are at level ERROR. + pub errors: u32, + /// How many lines of the block are at level WARN. + pub warnings: u32, +} + +impl Block { + /// Returns the milliseconds from the header to the handler's last line. + /// + /// This is how long the handler was logging, which is at most how long it ran; the time before + /// the header and after the last line is not in the log. For how long the handler took, at + /// least, see [`Pair::handler_ms`]. + #[must_use] + pub fn logged_ms(&self) -> f64 { + (self.end_mach_ns.saturating_sub(self.header_mach_ns)) as f64 / 1e6 + } +} + +const PUSHED: &str = "pushed notification to subscriber: "; + +/// Returns the handler blocks of a log, in the order their headers were logged. `lines` are in +/// file order. +/// +/// What a block's first and last line look like is komorebi's own business, so the `rules` of the +/// flavor that wrote the log say; what they have in common is that everything logged inside a +/// handler carries the handler's root span. For each line that has a time: +/// +/// - If [`Rules::block_header`] returns a header for the line, a new block starts, and the one that +/// was open is left as it was (it has no `finished_line`). +/// - Otherwise, a line whose root span is `process_event` or `process_command` joins the open block +/// when the kinds match: its number, time and level are added, and a `pushed notification` line +/// is recorded in `pushes`. When [`Rules::is_block_end`] returns `true` for it, the block is +/// closed and `finished_line` is set. +/// - Any other line is ambient and is in no block: one logged from another thread, one from a +/// handler of the other kind, one before the first header and one after the block ended. +/// +/// Continuation lines (a panic's text) are not looked at. A line whose time cannot be mapped to the +/// master clock (the session has no clock anchors, or the line has no time) is skipped. +/// +/// The list is empty when the log has no handler headers. +/// +/// See the [module documentation](self) for an example. +#[must_use] +pub fn build(lines: &[Line], clock: &ClockMap, rules: &dyn Rules) -> Vec { + let mach = |line: &Line| line.wall_us.and_then(|wall_us| clock.wall_to_mach(wall_us)); + + let mut blocks: Vec = Vec::new(); + let mut open: Option = None; + + for line in lines.iter().filter(|line| !line.continuation) { + let Some(time) = mach(line) else { + continue; + }; + + if let Some(header) = rules.block_header(line, open.map(|index| &blocks[index])) { + blocks.push(new_block(blocks.len(), header, line.number, time)); + open = Some(blocks.len() - 1); + continue; + } + + let Some(root @ ("process_event" | "process_command")) = line.root_span() else { + continue; + }; + let Some(index) = open else { + continue; + }; + let block = &mut blocks[index]; + let belongs = matches!( + (root, block.kind), + ("process_event", BlockKind::Event) | ("process_command", BlockKind::Command) + ); + if !belongs { + continue; + } + + block.lines.push(line.number); + block.last_line = line.number; + block.end_mach_ns = time; + match line.level { + Some(Level::Error) => block.errors += 1, + Some(Level::Warn) => block.warnings += 1, + _ => {} + } + + if let Some(subscriber) = line.message.strip_prefix(PUSHED) { + block.pushes.push(Push { + subscriber: subscriber.trim().to_string(), + line: line.number, + mach_ns: time, + }); + } + + if rules.is_block_end(line, block.kind) { + block.finished_line = Some(line.number); + open = None; + } + } + + blocks +} + +fn new_block(id: usize, header: BlockHeader, line: u64, time: u64) -> Block { + Block { + id, + kind: header.kind, + name: header.name, + pid: header.pid, + window_id: header.window_id, + notification: header.notification, + header_line: line, + header_mach_ns: time, + last_line: line, + end_mach_ns: time, + lines: vec![line], + finished_line: None, + pushes: Vec::new(), + errors: 0, + warnings: 0, + } +} + +/// How sure the pairing of an event with a handler is. +/// +/// Serialized in kebab case (`pushed`, `header`, `none`). +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, JsonSchema)] +#[serde(rename_all = "kebab-case")] +pub enum Quality { + /// komorebi logged handing the notification to this subscriber. + Pushed, + /// Matched by name, process and notification. + Header, + /// No block was found. + None, +} + +/// An event tied to the handler block that produced it, or to none. +/// +/// Made by [`pair`], one for each event. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct Pair { + /// The event's sequence number. + pub seq: u64, + /// The [`Block::id`] of the block that produced the event, or `None` if none was found. + pub block: Option, + /// How sure the pairing is. [`Quality::None`] exactly when `block` is `None`. + pub quality: Quality, + /// The `pushed notification` line for this event, if there was one. + pub pushed_line: Option, + /// Milliseconds from the handler's header to the event being received: how long the handler + /// took, at least. + pub handler_ms: Option, +} + +/// How far a log time may be from the recorder's own clock reading and still be taken to be the +/// same moment. The two are mapped through the clock anchors, which are accurate to about a +/// millisecond; the margin is for scheduling in between. +const SLACK_NS: u64 = 25_000_000; + +/// How close a `pushed notification` line must be before an event's receipt. +const PUSH_WINDOW_NS: u64 = 100_000_000; + +/// Returns the subscriber name the recorder registered as, found from which `pushed notification` +/// lines line up with the recorded events, or `None` if none does. +/// +/// komorebi logs the name of each subscriber it pushes a notification to. The recorder is the one +/// whose pushes come just before the events it recorded: a push counts for an event if it was +/// logged from 100 ms before the event was received to 25 ms after (the margin is for the clock +/// mapping and scheduling). The name with the most events lined up wins, and where two tie, a name +/// that starts `komorebi-recorder-` is preferred. +/// +/// A session records the name it registered as, which is better evidence; this is for the +/// sessions that do not. See [`pair`] for an example. +#[must_use] +pub fn infer_subscriber(blocks: &[Block], events: &[EventRecord]) -> Option { + let mut pushes: BTreeMap<&str, Vec> = BTreeMap::new(); + for push in blocks.iter().flat_map(|block| &block.pushes) { + pushes + .entry(push.subscriber.as_str()) + .or_default() + .push(push.mach_ns); + } + + let score = |times: &[u64]| { + events + .iter() + .filter(|event| { + times.iter().any(|time| { + *time <= event.recv_mach_ns + SLACK_NS + && event.recv_mach_ns <= *time + PUSH_WINDOW_NS + }) + }) + .count() + }; + + pushes + .into_iter() + .map(|(name, times)| { + // our own subscriber names start with this; prefer them on a tie + let ours = name.starts_with("komorebi-recorder-"); + (score(×), ours, name) + }) + .filter(|(score, _, _)| *score > 0) + .max_by_key(|(score, ours, _)| (*score, *ours)) + .map(|(_, _, name)| name.to_string()) +} + +/// The line where komorebi handed `block`'s notification to `subscriber`, if the log has it. +fn push_for<'a>( + block: &'a Block, + subscriber: Option<&str>, + recv_mach_ns: u64, + upper: u64, +) -> Option<&'a Push> { + let name = subscriber?; + block + .pushes + .iter() + .filter(|push| push.subscriber == name) + .filter(|push| push.mach_ns <= upper && recv_mach_ns <= push.mach_ns + PUSH_WINDOW_NS) + .max_by_key(|push| push.mach_ns) +} + +/// Returns, for each event, the block that produced it and how sure the pairing is. +/// +/// There is one [`Pair`] per event, in the same order. `events` must be in receipt order, which is +/// how [`events::load`](super::events::load) returns them. +/// +/// Each event is matched to a block in turn. The candidates are the blocks that no earlier event +/// took, of the kind the event's family has (a window-manager event pairs with an event block, a +/// command with a command block, and a monitor notification or an unreadable one with none), with +/// the same name, whose header was logged after the previous event was received and no later than +/// this one was (each with 25 ms of slack), and whose process, window handle and notification each +/// agree wherever both the block and the event have one. Of those, the block with the latest header +/// is taken: the handler that finished last before the notification. A block is paired with at most +/// one event. +/// +/// The pairing is [`Quality::Pushed`] when `subscriber` is given and the block has a +/// `pushed notification to subscriber:` line for it, logged from 100 ms before to 25 ms after the +/// event was received. Without a `subscriber`, a found block is [`Quality::Header`]. With no +/// block, the pair is [`Quality::None`] and has neither a block nor a handler time. A pairing is a +/// judgement from timing, and only a `Pushed` one is exact. +/// +/// # Performance +/// +/// Each event looks at every block, so the cost grows with events times blocks. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::analysis::blocks::{Quality, build, infer_subscriber, pair}; +/// use komorebi_recorder::analysis::events::EventRecord; +/// use komorebi_recorder::analysis::flavor::Flavor; +/// use komorebi_recorder::analysis::logparse; +/// use komorebi_recorder::clock::{Anchor, ClockMap}; +/// use serde_json::json; +/// +/// let log = "\ +/// 2026-10-26T23:09:16.100000Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 10 with notification AXWindowMoved +/// 2026-10-26T23:09:16.250000Z DEBUG process_event: komorebi::notify: pushed notification to subscriber: komorebi-recorder-4242 +/// "; +/// let lines = logparse::parse(log.as_bytes()); +/// let wall_us = chrono::DateTime::parse_from_rfc3339("2026-10-26T23:09:16Z")?.timestamp_micros(); +/// let clock = ClockMap::new(vec![ +/// Anchor { mach_ns: 1_000_000_000, wall_us }, +/// Anchor { mach_ns: 61_000_000_000, wall_us: wall_us + 60_000_000 }, +/// ]); +/// let blocks = build(&lines, &clock, Flavor::Macos.rules()); +/// +/// // the recorder received the notification 250.5 ms after the clock's anchor +/// let moved = json!({ +/// "type": "MoveEnd", +/// "content": [{"type": "Accessibility", "content": "AXWindowMoved"}, 10, 7] +/// }); +/// let events = vec![EventRecord { +/// seq: 1, +/// recv_mach_ns: 1_250_500_000, +/// recv_wall_us: 0, +/// state_id: None, +/// info: Flavor::Macos.rules().describe_event(&moved), +/// parse_error: None, +/// }]; +/// +/// // the log names the subscriber the push went to, so the pairing is exact +/// let subscriber = infer_subscriber(&blocks, &events); +/// assert_eq!(subscriber.as_deref(), Some("komorebi-recorder-4242")); +/// +/// let pairs = pair(&events, &blocks, subscriber.as_deref()); +/// assert_eq!(pairs[0].block, Some(0)); +/// assert_eq!(pairs[0].quality, Quality::Pushed); +/// assert_eq!(pairs[0].pushed_line, Some(2)); +/// // from the header (1.1 s) to the receipt (1.2505 s) +/// assert!((pairs[0].handler_ms.expect("a handler") - 150.5).abs() < 0.01); +/// +/// // without the subscriber's name it is matched by name, process and notification only +/// assert_eq!(pair(&events, &blocks, None)[0].quality, Quality::Header); +/// # Ok::<(), Box>(()) +/// ``` +#[must_use] +pub fn pair(events: &[EventRecord], blocks: &[Block], subscriber: Option<&str>) -> Vec { + let mut used = vec![false; blocks.len()]; + let mut previous_recv = 0_u64; + let mut pairs = Vec::with_capacity(events.len()); + + for event in events { + let upper = event.recv_mach_ns.saturating_add(SLACK_NS); + let lower = previous_recv.saturating_sub(SLACK_NS); + + let wanted = match event.info.family { + Family::WindowManager => Some(BlockKind::Event), + Family::Command => Some(BlockKind::Command), + Family::Monitor | Family::Unknown => None, + }; + + let candidate = wanted.and_then(|kind| { + blocks + .iter() + .filter(|block| { + !used[block.id] + && block.kind == kind + && block.name == event.info.name + && block.header_mach_ns > lower + && block.header_mach_ns <= upper + && match (&block.pid, &event.info.pid) { + (Some(a), Some(b)) => a == b, + _ => true, + } + && match (&block.window_id, &event.info.window_id) { + (Some(a), Some(b)) => a == b, + _ => true, + } + && match (&block.notification, &event.info.notification) { + (Some(a), Some(b)) => a == b, + _ => true, + } + }) + // the handler that finished last before the notification + .max_by_key(|block| block.header_mach_ns) + }); + + let pair = if let Some(block) = candidate { + used[block.id] = true; + let push = push_for(block, subscriber, event.recv_mach_ns, upper); + Pair { + seq: event.seq, + block: Some(block.id), + quality: if push.is_some() { + Quality::Pushed + } else { + Quality::Header + }, + pushed_line: push.map(|push| push.line), + handler_ms: Some( + event.recv_mach_ns.saturating_sub(block.header_mach_ns) as f64 / 1e6, + ), + } + } else { + Pair { + seq: event.seq, + block: None, + quality: Quality::None, + pushed_line: None, + handler_ms: None, + } + }; + + pairs.push(pair); + previous_recv = event.recv_mach_ns; + } + + pairs +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::analysis::flavor::Flavor; + use crate::analysis::logparse; + use crate::clock::Anchor; + use crate::testkit; + use serde_json::json; + + /// A clock where wall time is mach time plus the testkit's constant. + fn clock() -> ClockMap { + ClockMap::new(vec![ + Anchor { + mach_ns: testkit::mach_ns(-1.0), + wall_us: testkit::wall_us(-1.0), + }, + Anchor { + mach_ns: testkit::mach_ns(60.0), + wall_us: testkit::wall_us(60.0), + }, + ]) + } + + /// Log text from `(video_s, level, text-after-level)` lines, like komorebi's. + fn log(lines: &[(f64, &str, &str)]) -> Vec { + logparse::parse(testkit::log_text(lines).as_bytes()) + } + + fn event(seq: u64, video_s: f64, value: serde_json::Value) -> EventRecord { + EventRecord { + seq, + recv_mach_ns: testkit::mach_ns(video_s), + recv_wall_us: testkit::wall_us(video_s), + state_id: None, + info: Flavor::Macos.rules().describe_event(&value), + parse_error: None, + } + } + + fn move_end(pid: i64) -> serde_json::Value { + json!({"type": "MoveEnd", "content": [{"type": "Accessibility", "content": "AXWindowMoved"}, pid, 7]}) + } + + const HEADER: &str = "process_event: komorebi::process_event: processing event: MoveEnd for process 10 with notification AXWindowMoved"; + + #[test] + fn a_handlers_lines_are_everything_with_its_span_until_the_next_header() { + let lines = log(&[ + (1.0, "INFO", HEADER), + ( + 1.1, + "INFO", + "process_event:focus_window{idx=0}: komorebi::container: focusing window", + ), + ( + 1.15, + "INFO", + "komorebi::border_manager: invalidating border observer", + ), + ( + 1.2, + "WARN", + "process_event:update_focused_workspace: komorebi::workspace: failed to set window position: AXError::InvalidUIElement", + ), + ( + 2.0, + "INFO", + "process_event: komorebi::process_event: processing event: FocusChange for process 11 with notification AXApplicationActivated", + ), + ]); + + let blocks = build(&lines, &clock(), Flavor::Macos.rules()); + assert_eq!(blocks.len(), 2); + + let first = &blocks[0]; + assert_eq!(first.kind, BlockKind::Event); + assert_eq!(first.name, "MoveEnd"); + assert_eq!(first.pid, Some(10)); + assert_eq!(first.notification.as_deref(), Some("AXWindowMoved")); + // the border manager's line is ambient: logged from another thread, no handler span + assert_eq!(first.lines, [1, 2, 4]); + assert_eq!(first.warnings, 1); + assert!((first.logged_ms() - 200.0).abs() < 1.0); + + assert_eq!(blocks[1].name, "FocusChange"); + assert_eq!(blocks[1].lines, [5]); + } + + #[test] + fn a_command_block_ends_at_its_processed_line() { + let lines = log(&[ + ( + 1.0, + "INFO", + "process_command: komorebi::process_command: processing command: FocusWorkspaceNumber", + ), + ( + 1.1, + "INFO", + "process_command:focus_workspace{idx=0}: komorebi::window_manager: focusing workspace", + ), + ( + 1.3, + "INFO", + "process_command: komorebi::process_command: processed command: FocusWorkspaceNumber", + ), + // after the command ended: ambient again + ( + 1.4, + "INFO", + "process_command:something: komorebi::x: late line", + ), + ]); + + let blocks = build(&lines, &clock(), Flavor::Macos.rules()); + assert_eq!(blocks.len(), 1); + assert_eq!(blocks[0].kind, BlockKind::Command); + assert_eq!(blocks[0].name, "FocusWorkspaceNumber"); + assert_eq!(blocks[0].finished_line, Some(3)); + assert_eq!(blocks[0].lines, [1, 2, 3]); + } + + #[test] + fn handler_lines_before_any_header_belong_to_no_block() { + let lines = log(&[ + ( + 0.5, + "DEBUG", + "process_event: komorebi::process_event: ignoring event as window should not be managed: X", + ), + (1.0, "INFO", HEADER), + ]); + + let blocks = build(&lines, &clock(), Flavor::Macos.rules()); + assert_eq!(blocks.len(), 1); + assert_eq!(blocks[0].lines, [2]); + } + + #[test] + fn an_event_pairs_with_the_last_matching_header_before_it_was_received() { + let lines = log(&[(1.0, "INFO", HEADER), (3.0, "INFO", HEADER)]); + let blocks = build(&lines, &clock(), Flavor::Macos.rules()); + // received at 3.25s: the handler that began at 3.0s sent it; the one at 1.0s never did + let events = vec![event(1, 3.25, move_end(10))]; + + let pairs = pair(&events, &blocks, None); + assert_eq!(pairs[0].block, Some(1)); + assert_eq!(pairs[0].quality, Quality::Header); + assert!((pairs[0].handler_ms.expect("ms") - 250.0).abs() < 1.0); + } + + #[test] + fn an_event_is_not_paired_across_another_event() { + let lines = log(&[(1.0, "INFO", HEADER)]); + let blocks = build(&lines, &clock(), Flavor::Macos.rules()); + let events = vec![ + event(1, 1.1, move_end(10)), + // a second event of the same kind with no handler logged: it must not steal block 0 + event(2, 5.0, move_end(10)), + ]; + + let pairs = pair(&events, &blocks, None); + assert_eq!(pairs[0].block, Some(0)); + assert_eq!(pairs[1].block, None); + assert_eq!(pairs[1].quality, Quality::None); + } + + #[test] + fn name_process_and_notification_must_agree() { + let lines = log(&[(1.0, "INFO", HEADER)]); + let blocks = build(&lines, &clock(), Flavor::Macos.rules()); + + let other_process = pair(&[event(1, 1.1, move_end(99))], &blocks, None); + assert_eq!(other_process[0].block, None); + + let other_name = pair( + &[event( + 1, + 1.1, + json!({"type": "ResizeEnd", "content": [{"type": "Accessibility", "content": "AXWindowMoved"}, 10, 7]}), + )], + &blocks, + None, + ); + assert_eq!(other_name[0].block, None); + } + + #[test] + fn a_pushed_line_makes_the_pairing_exact_and_names_our_subscriber() { + let lines = log(&[ + (1.0, "INFO", HEADER), + ( + 1.2, + "DEBUG", + "process_event: komorebi::notify: pushed notification to subscriber: komorebi-bar-x", + ), + ( + 1.2001, + "DEBUG", + "process_event: komorebi::notify: pushed notification to subscriber: komorebi-recorder-4242", + ), + ]); + let blocks = build(&lines, &clock(), Flavor::Macos.rules()); + let events = vec![event(1, 1.2005, move_end(10))]; + + assert_eq!( + infer_subscriber(&blocks, &events).as_deref(), + Some("komorebi-recorder-4242") + ); + + let pairs = pair(&events, &blocks, Some("komorebi-recorder-4242")); + assert_eq!(pairs[0].quality, Quality::Pushed); + assert_eq!(pairs[0].pushed_line, Some(3)); + } + + #[test] + fn commands_and_monitor_events_pair_by_family() { + let lines = log(&[ + ( + 1.0, + "INFO", + "process_command: komorebi::process_command: processing command: Retile", + ), + ( + 1.2, + "INFO", + "process_command: komorebi::process_command: processed command: Retile", + ), + ]); + let blocks = build(&lines, &clock(), Flavor::Macos.rules()); + let events = vec![ + event(1, 1.1, json!({"type": "Retile"})), + event(2, 3.0, json!({"DisplayConnectionChange": 1})), + ]; + + let pairs = pair(&events, &blocks, None); + assert_eq!(pairs[0].block, Some(0)); + assert_eq!(pairs[1].block, None); + } + + /// Run with `--ignored` on a machine that runs komorebi: its real log must group into handler + /// blocks, and nearly every line must be found in the source. + #[test] + #[ignore = "reads the real komorebi log of the machine"] + fn the_real_log_groups_into_handlers() { + let dir = crate::komorebi_link::data_dir().to_path_buf(); + let newest = std::fs::read_dir(&dir) + .expect("data dir") + .filter_map(Result::ok) + .filter(|entry| { + entry + .file_name() + .to_string_lossy() + .starts_with(crate::sources::komorebi_log::PLAINTEXT_PREFIX) + }) + .max_by_key(|entry| entry.file_name()) + .expect("a plaintext log"); + let bytes = std::fs::read(newest.path()).expect("read"); + let lines = logparse::parse(&bytes); + + // wall time is mach time plus a constant, so any anchors will do + let first = lines + .iter() + .find_map(|line| line.wall_us) + .expect("a timestamp"); + let clock = ClockMap::new(vec![ + Anchor { + mach_ns: 1_000_000_000, + wall_us: first, + }, + Anchor { + mach_ns: 1_000_000_000 + 86_400_000_000_000, + wall_us: first + 86_400_000_000, + }, + ]); + let blocks = build(&lines, &clock, Flavor::Macos.rules()); + + let events = blocks + .iter() + .filter(|block| block.kind == BlockKind::Event) + .count(); + let commands = blocks + .iter() + .filter(|block| block.kind == BlockKind::Command) + .count(); + let in_blocks: usize = blocks.iter().map(|block| block.lines.len()).sum(); + let handler_lines = lines + .iter() + .filter(|line| matches!(line.root_span(), Some("process_event" | "process_command"))) + .count(); + + eprintln!( + "{} lines: {events} event blocks, {commands} command blocks holding {in_blocks} of {handler_lines} handler lines", + lines.len() + ); + assert!(events > 0); + assert!( + in_blocks * 10 >= handler_lines * 7, + "most handler lines are in a block" + ); + } +} diff --git a/komorebi-recorder/src/analysis/flavor/mac.rs b/komorebi-recorder/src/analysis/flavor/mac.rs index 85e0dfd4..9c0072de 100644 --- a/komorebi-recorder/src/analysis/flavor/mac.rs +++ b/komorebi-recorder/src/analysis/flavor/mac.rs @@ -24,12 +24,16 @@ //! //! [`verified`]: Rules::verified +use super::BlockHeader; use super::Flavor; use super::Rules; +use crate::analysis::blocks::Block; +use crate::analysis::blocks::BlockKind; use crate::analysis::classify::Class; use crate::analysis::events::EventInfo; use crate::analysis::events::EventRecord; use crate::analysis::events::Family; +use crate::analysis::logparse::Line; use serde_json::Value; /// The [`Rules`] of komorebi for Mac: what its events, `State`, log and modules say. @@ -58,6 +62,21 @@ const WINDOW_MANAGER_EVENTS: [&str; 14] = [ const GEOMETRY_EVENTS: [&str; 4] = ["MoveStart", "MoveEnd", "ResizeStart", "ResizeEnd"]; +const EVENT_HEADER: &str = "processing event: "; +const COMMAND_HEADER: &str = "processing command: "; +const COMMAND_FINISHED: &str = "processed command: "; + +/// `FocusChange for process 79469 with notification AXApplicationActivated` +fn parse_event_header(rest: &str) -> (String, Option, Option) { + let (name, tail) = rest.split_once(" for process ").unwrap_or((rest, "")); + let (pid, notification) = tail.split_once(" with notification ").unwrap_or((tail, "")); + ( + name.trim().to_string(), + pid.trim().parse().ok(), + Some(notification.trim().to_string()).filter(|text| !text.is_empty()), + ) +} + /// Whether a window-manager event was made up by komorebi itself rather than reported by macOS. fn is_synthesized(event: &EventRecord) -> bool { event @@ -194,6 +213,36 @@ impl Rules for MacRules { } } + fn block_header(&self, line: &Line, _open: Option<&Block>) -> Option { + match line.root_span() { + Some("process_event") if line.message.starts_with(EVENT_HEADER) => { + let (name, pid, notification) = + parse_event_header(&line.message[EVENT_HEADER.len()..]); + Some(BlockHeader { + kind: BlockKind::Event, + name, + pid, + window_id: None, + notification, + }) + } + Some("process_command") if line.message.starts_with(COMMAND_HEADER) => { + Some(BlockHeader { + kind: BlockKind::Command, + name: line.message[COMMAND_HEADER.len()..].trim().to_string(), + pid: None, + window_id: None, + notification: None, + }) + } + _ => None, + } + } + + fn is_block_end(&self, line: &Line, kind: BlockKind) -> bool { + kind == BlockKind::Command && line.message.starts_with(COMMAND_FINISHED) + } + fn slow_handler_cause(&self) -> &'static str { "slow accessibility calls into other applications, or waiting for the lock another handler held" } diff --git a/komorebi-recorder/src/analysis/flavor/mod.rs b/komorebi-recorder/src/analysis/flavor/mod.rs index e7fab16a..6015f950 100644 --- a/komorebi-recorder/src/analysis/flavor/mod.rs +++ b/komorebi-recorder/src/analysis/flavor/mod.rs @@ -40,6 +40,8 @@ //! | [`window_id`](Rules::window_id) | the id a window has in `State` | `Snapshot::parse` | `id` | `hwnd` | //! | [`window_is_unreadable`](Rules::window_is_unreadable) | whether komorebi failed to read a window | `Snapshot::parse` | the default: never | the title starts with `could not get window` | //! | [`hides_windows_by_position`](Rules::hides_windows_by_position) | whether a window's position shows that it is hidden | `Snapshot::hides_windows_by_position` | yes: parked at a corner | no: cloaked where it is | +//! | [`block_header`](Rules::block_header) | whether a log line starts a handler's block | `blocks::build` | the `processing event:` and `processing command:` lines | the first line of a `process_event{...}` or `process_command{...}` span whose fields differ from the open block's | +//! | [`is_block_end`](Rules::is_block_end) | whether a log line ends a handler's block | `blocks::build` | `processed command: ...`, for commands only | `processed: ...` for events, `processed` for commands | //! | [`slow_handler_cause`](Rules::slow_handler_cause) | what a slow handler was probably doing | the `overview` and `trace` answers | accessibility calls | Win32 calls | //! | [`verified`](Rules::verified) | whether the rules were checked against a recording | `Analysis::warnings` | the default: yes | no | //! | [`flavor`](Rules::flavor) | which flavor the rules are for | tests | [`Flavor::Macos`] | [`Flavor::Windows`] | @@ -74,6 +76,8 @@ //! [`classify_monitor`](Rules::classify_monitor), by the record's [`Family`], and //! [`is_geometry_event`](Rules::is_geometry_event) when it decides whether a button release //! that komorebi made up ended a real drag. +//! 1. `blocks::build` walks the log: `block_header` for every line, and +//! `is_block_end` for every line inside an open block. //! //! [`MacRules`]: mac::MacRules //! [`WindowsRules`]: windows::WindowsRules @@ -84,9 +88,12 @@ pub mod mac; pub mod windows; +use super::blocks::Block; +use super::blocks::BlockKind; use super::classify::Class; use super::events::EventInfo; use super::events::EventRecord; +use super::logparse::Line; use schemars::JsonSchema; use serde::Deserialize; use serde::Serialize; @@ -242,6 +249,27 @@ impl std::fmt::Display for Flavor { } } +/// The start of a handler's block of log lines. +/// +/// [`Rules::block_header`] returns one for the first line of a block, describing the handler that +/// line begins; `blocks::build` makes the `Block` from it. A field is `None` when the flavor's log +/// does not give it. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct BlockHeader { + /// Whether the handler is handling an event or a command (a `BlockKind`). + pub kind: BlockKind, + /// The event or command name: `MoveEnd`, `FocusWorkspaceNumber`, ... + pub name: String, + /// The process the event is about. komorebi for Mac logs it, and komorebi for Windows does not. + pub pid: Option, + /// The window handle, where the log gives one instead of a process. komorebi for Windows logs + /// it as the span field `hwnd`. + pub window_id: Option, + /// The notification the OS reported, e.g. `AXWindowMoved` on a Mac or `SystemForeground` on + /// Windows; `None` for a command. + pub notification: Option, +} + /// The vocabulary of one flavor of komorebi, as the questions the analysis asks of it. /// /// The role of this trait is to answer, for one komorebi, every question the analysis has about @@ -306,10 +334,12 @@ impl std::fmt::Display for Flavor { /// method written beyond the ones that have no default, and the others keep theirs: /// /// ```rust +/// # use komorebi_recorder::analysis::blocks::{Block, BlockKind}; /// # use komorebi_recorder::analysis::classify::Class; /// # use komorebi_recorder::analysis::events::{EventInfo, EventRecord}; /// # use komorebi_recorder::analysis::flavor::mac::MacRules; -/// # use komorebi_recorder::analysis::flavor::{Flavor, Rules}; +/// # use komorebi_recorder::analysis::flavor::{BlockHeader, Flavor, Rules}; +/// # use komorebi_recorder::analysis::logparse::Line; /// # use serde_json::Value; /// struct Unchecked; /// @@ -323,6 +353,12 @@ impl std::fmt::Display for Flavor { /// fn classify_window_manager(&self, event: &EventRecord) -> (Class, &'static str) { /// MacRules.classify_window_manager(event) /// } +/// fn block_header(&self, line: &Line, open: Option<&Block>) -> Option { +/// MacRules.block_header(line, open) +/// } +/// fn is_block_end(&self, line: &Line, kind: BlockKind) -> bool { +/// MacRules.is_block_end(line, kind) +/// } /// fn slow_handler_cause(&self) -> &'static str { MacRules.slow_handler_cause() } /// } /// @@ -340,10 +376,12 @@ impl std::fmt::Display for Flavor { /// implementor above without `slow_handler_cause`: /// /// ```rust,compile_fail,E0046 +/// # use komorebi_recorder::analysis::blocks::{Block, BlockKind}; /// # use komorebi_recorder::analysis::classify::Class; /// # use komorebi_recorder::analysis::events::{EventInfo, EventRecord}; /// # use komorebi_recorder::analysis::flavor::mac::MacRules; -/// # use komorebi_recorder::analysis::flavor::{Flavor, Rules}; +/// # use komorebi_recorder::analysis::flavor::{BlockHeader, Flavor, Rules}; +/// # use komorebi_recorder::analysis::logparse::Line; /// # use serde_json::Value; /// struct Unchecked; /// @@ -357,6 +395,12 @@ impl std::fmt::Display for Flavor { /// fn classify_window_manager(&self, event: &EventRecord) -> (Class, &'static str) { /// MacRules.classify_window_manager(event) /// } +/// fn block_header(&self, line: &Line, open: Option<&Block>) -> Option { +/// MacRules.block_header(line, open) +/// } +/// fn is_block_end(&self, line: &Line, kind: BlockKind) -> bool { +/// MacRules.is_block_end(line, kind) +/// } /// // no `slow_handler_cause` /// } /// ``` @@ -471,6 +515,28 @@ pub trait Rules: Sync { /// komorebi acted, into an echo itself. fn classify_window_manager(&self, event: &EventRecord) -> (Class, &'static str); + /// Returns the header of the handler's block that `line` starts, or `None` if `line` does not + /// start one. + /// + /// `open` is the block that has been collecting lines and has not ended. komorebi for Mac + /// logs a header line (`processing event: ...` or `processing command: ...`) and ignores + /// `open`. komorebi for Windows has no header line: its lines carry a span such as + /// `process_event{event="FocusChange" winevent="SystemForeground" hwnd=131072}`, and a new + /// handler has begun when the span's fields differ from the open block's. Two consecutive + /// handlers whose spans carry the same fields, with no end line between them, are therefore + /// one block. + fn block_header(&self, line: &Line, open: Option<&Block>) -> Option; + + /// Returns whether `line`, which belongs to a block of `kind`, is the one that marks the + /// handler as done. + /// + /// It is asked of the lines that were added to an open block, not of the line that started + /// it. A flavor whose log has no such line never ends a block that way. komorebi for Mac + /// logs `processed command: ...` for a command and nothing for an event. komorebi for + /// Windows logs `processed: ` for an event (at INFO, or TRACE for the noisiest + /// ones) and `processed` for a command. + fn is_block_end(&self, line: &Line, kind: BlockKind) -> bool; + /// Returns what a handler that took long was most likely doing, as a phrase that completes a /// sentence such as "took at least 250 ms to handle: ...". /// diff --git a/komorebi-recorder/src/analysis/flavor/windows.rs b/komorebi-recorder/src/analysis/flavor/windows.rs index 1f8cf05e..ca40e4eb 100644 --- a/komorebi-recorder/src/analysis/flavor/windows.rs +++ b/komorebi-recorder/src/analysis/flavor/windows.rs @@ -25,12 +25,16 @@ //! shows a window as hidden: [`Rules::hides_windows_by_position`] is `false` and //! `Rules::is_hidden_position` never matches. +use super::BlockHeader; use super::Flavor; use super::Rules; +use crate::analysis::blocks::Block; +use crate::analysis::blocks::BlockKind; use crate::analysis::classify::Class; use crate::analysis::events::EventInfo; use crate::analysis::events::EventRecord; use crate::analysis::events::Family; +use crate::analysis::logparse::Line; use serde_json::Value; /// The [`Rules`] of komorebi for Windows: what its events, `State`, log and modules say. @@ -95,6 +99,11 @@ fn handle(window: &Value) -> Option { .and_then(|hwnd| u32::try_from(hwnd).ok()) } +/// A span field's value: tracing prints a string field in quotes and a number bare. +fn unquoted(value: &str) -> &str { + value.trim().trim_matches('"') +} + impl Rules for WindowsRules { fn flavor(&self) -> Flavor { Flavor::Windows @@ -235,6 +244,66 @@ impl Rules for WindowsRules { false } + fn block_header(&self, line: &Line, open: Option<&Block>) -> Option { + let kind = match line.root_span()? { + "process_event" => BlockKind::Event, + "process_command" => BlockKind::Command, + _ => return None, + }; + + let root = line.spans.first()?; + let get = |key: &str| { + root.fields + .iter() + .find(|(name, _)| name == key) + .map(|(_, value)| unquoted(value).to_string()) + }; + + let header = match kind { + BlockKind::Event => BlockHeader { + kind, + name: get("event").unwrap_or_default(), + pid: None, + window_id: get("hwnd").and_then(|hwnd| hwnd.parse().ok()), + notification: get("winevent").filter(|winevent| winevent != "None"), + }, + BlockKind::Command => BlockHeader { + kind, + // `message=FocusWindow(Left)`: the command's name is what is before any argument + name: get("message") + .map(|message| { + message + .split(['(', ' ', '{']) + .next() + .unwrap_or_default() + .to_string() + }) + .unwrap_or_default(), + pid: None, + window_id: None, + notification: None, + }, + }; + + // the handler that is open carries on while its span says the same thing and it has not + // logged that it finished; a different span, or the end, starts a new one + let continues = open.is_some_and(|block| { + block.kind == header.kind + && block.name == header.name + && block.window_id == header.window_id + && block.notification == header.notification + }); + (!continues).then_some(header) + } + + fn is_block_end(&self, line: &Line, kind: BlockKind) -> bool { + match kind { + // INFO `processed: (hwnd: ...)`, or TRACE for the noisiest events + BlockKind::Event => line.message.starts_with("processed: "), + BlockKind::Command => line.message == "processed", + } + } + fn slow_handler_cause(&self) -> &'static str { "slow Win32 calls into other programs' windows (positioning one that is busy or hung, or an animation), or waiting for the lock another handler held" } diff --git a/komorebi-recorder/src/analysis/logparse.rs b/komorebi-recorder/src/analysis/logparse.rs new file mode 100644 index 00000000..62528d05 --- /dev/null +++ b/komorebi-recorder/src/analysis/logparse.rs @@ -0,0 +1,618 @@ +//! Reading komorebi's plaintext log as structured lines. +//! +//! komorebi logs with `tracing_subscriber`'s formatter, so a line is +//! +//! ```text +//! 2026-10-26T23:09:16.688494Z INFO process_event:focus_window{idx=0}: komorebi::container: focusing window +//! ``` +//! +//! a time, a level, the chain of *spans* the code was inside (`process_event` then `focus_window` +//! with its fields), the *target* (the module that logged), and the message. The span chain is what +//! lets a line be tied to the handler that ran: everything logged while handling one event or +//! command starts with that handler's span. Lines with no timestamp (panic messages, backtraces) +//! belong to the line before them. +//! +//! The "plaintext" log still carries ANSI escape codes inside span fields, so they are stripped +//! before parsing. +//! +//! [`parse`] reads a whole slice of a log into [`Line`]s and [`parse_line`] reads one. Reading +//! never fails: a line that does not have the expected shape is a [`Line`] with less in it (no +//! level, no spans, no target), and the text is kept in `message`. The groups of lines that belong +//! to one handler are found from the result by [`super::blocks`], and what those lines mean by the +//! flavor's rules. +//! +//! # Example +//! +//! ```rust +//! use komorebi_recorder::analysis::logparse::{Level, parse}; +//! +//! let log = b"\ +//! 2026-10-26T23:09:16.688494Z INFO process_event:focus_window{idx=0}: komorebi::container: focusing window +//! thread 'main' panicked at src/x.rs:1:1: +//! "; +//! let lines = parse(log); +//! assert_eq!(lines.len(), 2); +//! +//! let line = &lines[0]; +//! assert_eq!(line.level, Some(Level::Info)); +//! assert_eq!(line.root_span(), Some("process_event")); +//! assert_eq!(line.field("idx"), Some("0")); +//! assert_eq!(line.target.as_deref(), Some("komorebi::container")); +//! assert_eq!(line.message, "focusing window"); +//! +//! // a line with no timestamp belongs to the line before it +//! assert!(lines[1].continuation); +//! assert_eq!(lines[1].wall_us, lines[0].wall_us); +//! ``` + +use crate::sources::komorebi_log; +use crate::timeline::strip_ansi; +use chrono::DateTime; +use chrono::Utc; +use schemars::JsonSchema; +use serde::Serialize; + +/// The level of a log line: `tracing`'s five, from the most severe. +/// +/// Levels are ordered from the most severe to the most verbose, so `Level::Error < Level::Trace`, +/// and serialized in uppercase (`"ERROR"`, `"WARN"`, `"INFO"`, `"DEBUG"`, `"TRACE"`), as the log +/// spells them. +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, JsonSchema)] +#[serde(rename_all = "UPPERCASE")] +pub enum Level { + /// Something failed. + Error, + /// Something looked wrong but komorebi carried on. + Warn, + /// An ordinary event worth recording. komorebi's default level. + Info, + /// Detail for someone debugging komorebi. + Debug, + /// The finest detail: what komorebi logs only when asked to. + Trace, +} + +impl Level { + fn parse(text: &str) -> Option { + match text { + "ERROR" => Some(Self::Error), + "WARN" => Some(Self::Warn), + "INFO" => Some(Self::Info), + "DEBUG" => Some(Self::Debug), + "TRACE" => Some(Self::Trace), + _ => None, + } + } +} + +/// One span the code was inside when it logged. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)] +pub struct Span { + /// The span's name: `process_event`, `focus_window`. + pub name: String, + /// The span's fields as `(name, value)` pairs, in the order the log has them. A value is as the + /// log prints it, with ANSI escapes removed and the quotes around a string value taken off; + /// escapes inside the quotes are not decoded. + pub fields: Vec<(String, String)>, +} + +/// One line of the recorded log. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct Line { + /// 1-based line number in the session's `komorebi.log`. + pub number: u64, + /// The line's wall-clock time in microseconds since the epoch, or the previous line's for a + /// continuation. + pub wall_us: Option, + /// No timestamp of its own: a panic message or backtrace frame. + pub continuation: bool, + /// The line's level. `None` for a continuation, and for a line whose level is not one of the + /// five. + pub level: Option, + /// The spans the code was inside, outermost first. Empty for a line logged outside any span, + /// such as one from another thread. + pub spans: Vec, + /// The module that logged, e.g. `komorebi::container`. `None` for a continuation and for a line + /// in which none was found. + pub target: Option, + /// The message with ANSI escapes removed. For a continuation, the whole line. + pub message: String, +} + +impl Line { + /// Returns the name of the outermost span, which identifies the handler or task the line was + /// logged from, or `None` if the line was logged outside any span. + #[must_use] + pub fn root_span(&self) -> Option<&str> { + self.spans.first().map(|span| span.name.as_str()) + } + + /// Returns the value of the field called `name` of any span of the line, or `None` if no span + /// has one. If several spans have a field of that name, it is the outermost span's. + #[must_use] + pub fn field(&self, name: &str) -> Option<&str> { + self.spans + .iter() + .flat_map(|span| span.fields.iter()) + .find(|(key, _)| key == name) + .map(|(_, value)| value.as_str()) + } +} + +/// Returns the lines of a log slice, parsed: one [`Line`] for each line of `slice`, in file order, +/// numbered from 1. +/// +/// A line that does not start with a timestamp is a continuation, and takes the time of the line +/// before it. Bytes that are not UTF-8 are replaced, and ANSI escape codes are removed (see +/// [`strip_ansi`]) before a line is read. +/// +/// The first line of `slice` is line 1, so for a slice that is not a whole log the numbers are +/// relative to its start. +#[must_use] +pub fn parse(slice: &[u8]) -> Vec { + komorebi_log::index_lines(slice) + .into_iter() + .map(|indexed| { + let start = indexed.offset as usize; + let end = start + indexed.len as usize; + let raw = String::from_utf8_lossy(&slice[start..end]); + let text = strip_ansi(raw.trim_end_matches(['\n', '\r'])); + parse_line( + indexed.number, + &text, + indexed.timestamp, + indexed.is_continuation, + ) + }) + .collect() +} + +/// Returns one ANSI-free line, parsed. +/// +/// `number` is the line's number in its log. `time` is the timestamp the log's reader found for it +/// (see [`komorebi_log::index_lines`]): the timestamp at the start of `text` is skipped, not read +/// again, so `time` is what [`Line::wall_us`] is made from. A `continuation` is a line with no +/// timestamp of its own; it is not read for a level, spans or a target, and `text` is its +/// message. +/// +/// A line that is not a continuation but whose second word is not a level has no level, spans or +/// target, and its message is the text after the timestamp. +/// +/// # Example +/// +/// Quoted field values may hold spaces and braces, and a target that is a single word is not mistaken +/// for a span: +/// +/// ```rust +/// use komorebi_recorder::analysis::logparse::{Level, parse_line}; +/// +/// let line = parse_line( +/// 3, +/// r#"2026-10-26T03:37:19.781106Z WARN process_event:observe{title="A {weird} title" pid=7}: komorebi::application: registered"#, +/// None, +/// false, +/// ); +/// assert_eq!(line.number, 3); +/// assert_eq!(line.level, Some(Level::Warn)); +/// assert_eq!(line.field("title"), Some("A {weird} title")); +/// assert_eq!(line.field("pid"), Some("7")); +/// assert_eq!(line.message, "registered"); +/// +/// let line = parse_line(4, "2026-10-26T03:37:19.1Z INFO komorebi: started", None, false); +/// assert!(line.spans.is_empty()); +/// assert_eq!(line.target.as_deref(), Some("komorebi")); +/// ``` +#[must_use] +pub fn parse_line( + number: u64, + text: &str, + time: Option>, + continuation: bool, +) -> Line { + if continuation { + return Line { + number, + wall_us: time.map(|time| time.timestamp_micros()), + continuation, + level: None, + spans: Vec::new(), + target: None, + message: text.to_string(), + }; + } + + // `