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.
This commit is contained in:
LGUG2Z committed 2026-10-27 22:22:56 -07:00
1 parent e3a1f01fd7
commit af6e332fed
7 files changed
+1678 -2

No files matched your search

+817
View File
@@ -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: <us>` (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<dyn std::error::Error>>(())
//! ```
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: <name>`, 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<i32>,
/// 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<u32>,
/// The notification the OS reported, e.g. `AXWindowMoved`, where the log gives it; `None` for a
/// command.
pub notification: Option<String>,
/// 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<u64>,
/// The line saying the handler finished, for the flavors whose log has one (`processed command:`
/// on a Mac, for commands only; `processed` and `processed: <window>` on Windows).
pub finished_line: Option<u64>,
/// The lines in which komorebi handed a notification to a subscriber, in order.
pub pushes: Vec<Push>,
/// 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<Block> {
let mach = |line: &Line| line.wall_us.and_then(|wall_us| clock.wall_to_mach(wall_us));
let mut blocks: Vec<Block> = Vec::new();
let mut open: Option<usize> = 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<usize>,
/// 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<u64>,
/// Milliseconds from the handler's header to the event being received: how long the handler
/// took, at least.
pub handler_ms: Option<f64>,
}
/// 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<String> {
let mut pushes: BTreeMap<&str, Vec<u64>> = 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(&times), 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<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn pair(events: &[EventRecord], blocks: &[Block], subscriber: Option<&str>) -> Vec<Pair> {
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<Line> {
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"
);
}
}
@@ -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<i32>, Option<String>) {
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<BlockHeader> {
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"
}
+68 -2
View File
@@ -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<i32>,
/// 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<u32>,
/// The notification the OS reported, e.g. `AXWindowMoved` on a Mac or `SystemForeground` on
/// Windows; `None` for a command.
pub notification: Option<String>,
}
/// 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<BlockHeader> {
/// 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<BlockHeader> {
/// 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<BlockHeader>;
/// 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: <window>` 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: ...".
///
@@ -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<u32> {
.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<BlockHeader> {
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"
}
+618
View File
@@ -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<Self> {
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<i64>,
/// 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<Level>,
/// 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<Span>,
/// The module that logged, e.g. `komorebi::container`. `None` for a continuation and for a line
/// in which none was found.
pub target: Option<String>,
/// 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<Line> {
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<DateTime<Utc>>,
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(),
};
}
// `<time> <level> <body>`; the level is right-aligned so there can be two spaces
let mut parts = text.splitn(2, char::is_whitespace);
let _timestamp = parts.next();
let after_time = parts.next().unwrap_or("").trim_start();
let (level_text, body) = after_time
.split_once(char::is_whitespace)
.unwrap_or((after_time, ""));
let Some(level) = Level::parse(level_text) else {
return Line {
number,
wall_us: time.map(|time| time.timestamp_micros()),
continuation: false,
level: None,
spans: Vec::new(),
target: None,
message: after_time.to_string(),
};
};
let (spans, target, message) = parse_body(body.trim_start());
Line {
number,
wall_us: time.map(|time| time.timestamp_micros()),
continuation: false,
level: Some(level),
spans,
target,
message,
}
}
fn is_ident(character: char) -> bool {
character.is_alphanumeric() || character == '_'
}
/// Split `{...}` off the front of `text`, honoring quotes, returning the inside and what follows.
fn braced(text: &str) -> Option<(&str, &str)> {
let mut depth = 0_u32;
let mut quoted = false;
let mut escaped = false;
for (index, character) in text.char_indices() {
if quoted {
match character {
_ if escaped => escaped = false,
'\\' => escaped = true,
'"' => quoted = false,
_ => {}
}
continue;
}
match character {
'"' => quoted = true,
'{' => depth += 1,
'}' => {
depth -= 1;
if depth == 0 {
return Some((&text[1..index], &text[index + 1..]));
}
}
_ => {}
}
}
None
}
fn parse_fields(text: &str) -> Vec<(String, String)> {
let mut fields = Vec::new();
let mut rest = text.trim();
while !rest.is_empty() {
let Some((key, after)) = rest.split_once('=') else {
break;
};
let (value, remainder) = if let Some(quoted) = after.strip_prefix('"') {
let mut end = quoted.len();
let mut escaped = false;
for (index, character) in quoted.char_indices() {
match character {
_ if escaped => escaped = false,
'\\' => escaped = true,
'"' => {
end = index;
break;
}
_ => {}
}
}
(&quoted[..end], quoted.get(end + 1..).unwrap_or(""))
} else {
let end = after.find(' ').unwrap_or(after.len());
(&after[..end], &after[end..])
};
fields.push((key.trim().to_string(), value.to_string()));
rest = remainder.trim_start();
}
fields
}
/// The span chain, target and message of the part of a line after its level.
fn parse_body(body: &str) -> (Vec<Span>, Option<String>, String) {
let mut spans = Vec::new();
let mut cursor = body;
// spans: `name`, `name{fields}`, joined by `:`; the chain ends at `: `
loop {
let ident_len = cursor.find(|c: char| !is_ident(c)).unwrap_or(cursor.len());
if ident_len == 0 {
break;
}
let name = &cursor[..ident_len];
let after = &cursor[ident_len..];
// `komorebi::x` is a target, not a span
if after.starts_with("::") || after.is_empty() {
break;
}
let (fields, tail) = if after.starts_with('{') {
match braced(after) {
Some((inside, tail)) => (parse_fields(inside), tail),
None => break,
}
} else {
(Vec::new(), after)
};
if let Some(rest) = tail.strip_prefix(": ") {
spans.push(Span {
name: name.to_string(),
fields,
});
cursor = rest;
break;
}
if let Some(rest) = tail.strip_prefix(':') {
spans.push(Span {
name: name.to_string(),
fields,
});
cursor = rest;
continue;
}
break;
}
// the target: `a::b::c: ` (a lone `komorebi: ` also counts)
let target_len = cursor
.find(|c: char| !(is_ident(c) || c == ':'))
.unwrap_or(cursor.len());
let candidate = &cursor[..target_len];
if let Some(target) = candidate.strip_suffix(':')
&& !target.is_empty()
&& !target.ends_with(':')
&& cursor[target_len..].starts_with(' ')
{
return (
spans,
Some(target.to_string()),
cursor[target_len + 1..].to_string(),
);
}
// no target: what looked like the last span may have been a single-word target
if spans.last().is_some_and(|last| last.fields.is_empty())
&& let Some(last) = spans.pop()
{
return (spans, Some(last.name), cursor.to_string());
}
(spans, None, cursor.to_string())
}
#[cfg(test)]
mod tests {
use super::*;
const SAMPLE: &str = include_str!("../../tests/fixtures/komorebi_plaintext_sample.log");
fn line(text: &str) -> Line {
let time = komorebi_log::parse_timestamp(text);
parse_line(1, &strip_ansi(text), time, time.is_none())
}
#[test]
fn a_handler_header_has_one_span_a_target_and_a_message() {
let parsed = line(
"2026-10-26T23:09:16.685293Z INFO process_event: komorebi::process_event: processing event: FocusChange for process 79469 with notification NSWorkspaceDidActivateApplicationNotification",
);
assert_eq!(parsed.level, Some(Level::Info));
assert_eq!(parsed.root_span(), Some("process_event"));
assert_eq!(parsed.spans.len(), 1);
assert_eq!(parsed.target.as_deref(), Some("komorebi::process_event"));
assert_eq!(
parsed.message,
"processing event: FocusChange for process 79469 with notification NSWorkspaceDidActivateApplicationNotification"
);
assert!(parsed.wall_us.is_some());
}
#[test]
fn a_line_logged_from_another_thread_has_no_span() {
let parsed = line(
"2026-10-26T23:09:16.610799Z INFO komorebi::border_manager: invalidating border observer",
);
assert!(parsed.spans.is_empty());
assert_eq!(parsed.root_span(), None);
assert_eq!(parsed.target.as_deref(), Some("komorebi::border_manager"));
assert_eq!(parsed.message, "invalidating border observer");
}
#[test]
fn nested_spans_keep_their_fields_after_the_ansi_is_stripped() {
let raw = "2026-10-26T23:09:16.688494Z INFO process_event:focus_window{\u{1b}[3midx\u{1b}[0m\u{1b}[2m=\u{1b}[0m0}: komorebi::container: focusing window";
let parsed = parse(raw.as_bytes()).remove(0);
assert_eq!(
parsed.spans,
vec![
Span {
name: "process_event".to_string(),
fields: vec![]
},
Span {
name: "focus_window".to_string(),
fields: vec![("idx".to_string(), "0".to_string())]
},
]
);
assert_eq!(parsed.field("idx"), Some("0"));
assert_eq!(parsed.target.as_deref(), Some("komorebi::container"));
assert_eq!(parsed.message, "focusing window");
}
#[test]
fn spans_with_several_fields_and_a_span_after_them_parse() {
let parsed = line(
"2026-10-26T03:37:19.781106Z ERROR process_event:update_focused_workspace{follow_focus=true trigger_focus=false}:update_focused_workspace:window_rect: komorebi::macos_api: failed to get window position: AXError::InvalidUIElement",
);
let names: Vec<&str> = parsed.spans.iter().map(|span| span.name.as_str()).collect();
assert_eq!(
names,
[
"process_event",
"update_focused_workspace",
"update_focused_workspace",
"window_rect"
]
);
assert_eq!(parsed.field("follow_focus"), Some("true"));
assert_eq!(parsed.field("trigger_focus"), Some("false"));
assert_eq!(parsed.level, Some(Level::Error));
assert_eq!(parsed.target.as_deref(), Some("komorebi::macos_api"));
assert_eq!(
parsed.message,
"failed to get window position: AXError::InvalidUIElement"
);
}
#[test]
fn quoted_field_values_may_contain_spaces_and_braces() {
let parsed = line(
r#"2026-10-26T03:37:19.781106Z INFO process_event:observe{title="A {weird} title" pid=7}: komorebi::application: registered"#,
);
assert_eq!(parsed.field("title"), Some("A {weird} title"));
assert_eq!(parsed.field("pid"), Some("7"));
assert_eq!(parsed.target.as_deref(), Some("komorebi::application"));
assert_eq!(parsed.message, "registered");
}
#[test]
fn a_message_containing_colons_is_not_mistaken_for_structure() {
let parsed = line(
"2026-10-26T03:37:19.1Z WARN komorebi::application: failed to register observer for process 7 (X): AXError::CannotComplete, 3 retries left",
);
assert!(parsed.spans.is_empty());
assert_eq!(parsed.target.as_deref(), Some("komorebi::application"));
assert_eq!(
parsed.message,
"failed to register observer for process 7 (X): AXError::CannotComplete, 3 retries left"
);
}
#[test]
fn a_single_word_target_is_not_taken_for_a_span() {
let parsed = line("2026-10-26T03:37:19.1Z INFO komorebi: started");
assert!(parsed.spans.is_empty());
assert_eq!(parsed.target.as_deref(), Some("komorebi"));
assert_eq!(parsed.message, "started");
}
#[test]
fn continuation_lines_take_the_time_of_the_line_before() {
let parsed = parse(
b"2026-10-26T03:37:19.703632Z INFO komorebi::x: before\nthread 'main' panicked at src/x.rs:1:1:\n 0: frame\n",
);
assert_eq!(parsed.len(), 3);
assert!(!parsed[0].continuation);
assert!(parsed[1].continuation && parsed[2].continuation);
assert_eq!(parsed[1].wall_us, parsed[0].wall_us);
assert_eq!(parsed[1].message, "thread 'main' panicked at src/x.rs:1:1:");
assert_eq!(parsed[2].level, None);
}
#[test]
fn every_line_of_a_real_log_parses_into_levels_and_targets() {
let parsed = parse(SAMPLE.as_bytes());
assert_eq!(parsed.len(), SAMPLE.lines().count());
let structured: Vec<&Line> = parsed.iter().filter(|line| !line.continuation).collect();
assert!(structured.len() > 40);
for line in &structured {
assert!(line.level.is_some(), "line {} has no level", line.number);
assert!(
line.target
.as_deref()
.is_some_and(|target| target.starts_with("komorebi")),
"line {} has no komorebi target: {line:?}",
line.number
);
assert!(
!line.message.is_empty(),
"line {} has no message",
line.number
);
assert!(
!line.message.contains('\u{1b}'),
"line {} still has ANSI in its message",
line.number
);
}
// the span chains of the real log were recovered
assert!(
parsed
.iter()
.any(|line| line.root_span() == Some("process_event"))
);
assert!(parsed.iter().any(|line| line.field("idx") == Some("0")));
assert!(parsed.iter().any(|line| line.level == Some(Level::Error)));
assert!(parsed.iter().any(|line| line.level == Some(Level::Warn)));
}
/// Run with `--ignored` on a machine that runs komorebi: every line of its newest real log
/// must parse, so a komorebi that logs differently is noticed.
#[test]
#[ignore = "reads the real komorebi log of the machine"]
fn the_newest_real_log_parses_completely() {
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(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 parsed = parse(&bytes);
let structured: Vec<&Line> = parsed.iter().filter(|line| !line.continuation).collect();
let without_target = structured
.iter()
.filter(|line| line.target.is_none())
.count();
let without_level = structured
.iter()
.filter(|line| line.level.is_none())
.count();
eprintln!(
"{}: {} lines, {} structured, {without_target} without a target, {without_level} without a level",
newest.path().display(),
parsed.len(),
structured.len()
);
assert_eq!(without_level, 0);
assert!(without_target * 1000 <= structured.len());
}
}
+2
View File
@@ -6,10 +6,12 @@
//! ([`envelope`]), how a point in time is named ([`timespec`], [`ids`]) and the guard that keeps
//! file access inside the session ([`guard`]).
pub mod blocks;
pub mod classify;
pub mod envelope;
pub mod events;
pub mod flavor;
pub mod guard;
pub mod ids;
pub mod logparse;
pub mod timespec;
@@ -0,0 +1,55 @@
2026-10-26T03:17:17.188982Z INFO process_event:focus_container{idx=0}: komorebi::workspace: focusing container
2026-10-26T03:17:17.214014Z INFO process_event: komorebi::process_event: processing event: FocusChange for process 20934 with notification AXApplicationActivated
2026-10-26T03:17:17.216855Z INFO process_event:focus_window{idx=0}: komorebi::container: focusing window
2026-10-26T03:17:17.216865Z INFO process_event:focus_container{idx=0}: komorebi::workspace: focusing container
2026-10-26T03:37:19.703632Z INFO process_event: komorebi::process_event: processing event: FocusChange for process 681 with notification AXApplicationActivated
2026-10-26T03:37:19.781106Z ERROR process_event:update_focused_workspace{follow_focus=true trigger_focus=false}:update_focused_workspace:window_rect: komorebi::macos_api: failed to get window position: AXError::InvalidUIElement
2026-10-26T03:37:19.783788Z WARN process_event:update_focused_workspace{follow_focus=true trigger_focus=false}:update_focused_workspace: komorebi::workspace: failed to set window position: AXError::InvalidUIElement
2026-10-26T03:37:19.784070Z ERROR process_event:update_focused_workspace{follow_focus=true trigger_focus=false}:update_focused_workspace:window_rect: komorebi::macos_api: failed to get window position: AXError::InvalidUIElement
2026-10-26T03:37:19.784980Z WARN process_event:update_focused_workspace{follow_focus=true trigger_focus=false}:update_focused_workspace: komorebi::workspace: failed to set window position: AXError::InvalidUIElement
2026-10-26T03:37:19.785498Z ERROR process_event:update_focused_workspace{follow_focus=true trigger_focus=false}:update_focused_workspace:window_rect: komorebi::macos_api: failed to get window position: AXError::InvalidUIElement
2026-10-26T03:37:19.786441Z WARN process_event:update_focused_workspace{follow_focus=true trigger_focus=false}:update_focused_workspace: komorebi::workspace: failed to set window position: AXError::InvalidUIElement
2026-10-26T03:37:19.814623Z INFO process_event: komorebi::window: invalidating window observer for <NO TITLE FOUND>
2026-10-26T03:37:19.815152Z INFO process_event: komorebi::window: invalidating window observer for <NO TITLE FOUND>
2026-10-26T03:37:19.815516Z INFO process_event: komorebi::window: invalidating window observer for <NO TITLE FOUND>
2026-10-26T03:37:19.815854Z INFO process_event: komorebi::window: invalidating window observer for <NO TITLE FOUND>
2026-10-26T03:37:19.816454Z INFO process_event: komorebi::window: invalidating window observer for <NO TITLE FOUND>
2026-10-26T03:37:19.817274Z INFO process_event: komorebi::window: invalidating window observer for <NO TITLE FOUND>
thread 'main' panicked at komorebi/src/example.rs:1:1:
0: backtrace frame
2026-10-26T23:09:16.612287Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 1942 with notification AXWindowMoved
2026-10-26T23:09:16.622615Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 72441 with notification AXWindowMoved
2026-10-26T23:09:16.630261Z INFO komorebi::border_manager: invalidating border observer
2026-10-26T23:09:16.642847Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 79469 with notification AXWindowMoved
2026-10-26T23:09:16.643436Z INFO komorebi::border_manager: invalidating border observer
2026-10-26T23:09:16.653486Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 96328 with notification AXWindowMoved
2026-10-26T23:09:16.664319Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 47907 with notification AXWindowMoved
2026-10-26T23:09:16.685293Z INFO process_event: komorebi::process_event: processing event: FocusChange for process 79469 with notification NSWorkspaceDidActivateApplicationNotification
2026-10-26T23:09:16.688494Z INFO process_event:focus_window{idx=0}: komorebi::container: focusing window
2026-10-26T23:09:16.688514Z INFO process_event:focus_container{idx=0}: komorebi::workspace: focusing container
2026-10-26T23:09:16.698081Z INFO process_event: komorebi::process_event: processing event: FocusChange for process 79469 with notification AXApplicationActivated
2026-10-26T23:09:16.700732Z INFO process_event:focus_window{idx=0}: komorebi::container: focusing window
2026-10-26T23:09:16.700745Z INFO process_event:focus_container{idx=0}: komorebi::workspace: focusing container
2026-10-26T23:09:17.733307Z INFO process_command: komorebi::process_command: processing command: FocusWorkspaceNumber
2026-10-26T23:09:17.733352Z INFO process_command:focus_workspace{idx=0}: komorebi::window_manager: focusing workspace
2026-10-26T23:09:17.733359Z INFO process_command:focus_workspace{idx=0}:focus_workspace{idx=0}: komorebi::monitor: focusing workspace
2026-10-26T23:09:17.756767Z INFO process_command:focus_workspace{idx=0}:focus_window{idx=0}: komorebi::container: focusing window
2026-10-26T23:09:17.887836Z INFO process_command: komorebi::process_command: processed command: FocusWorkspaceNumber
2026-10-26T23:09:17.889498Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 79469 with notification AXWindowMoved
2026-10-26T23:09:17.901710Z INFO komorebi::border_manager: invalidating border observer
2026-10-26T23:09:17.902705Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 96328 with notification AXWindowMoved
2026-10-26T23:09:17.915306Z INFO komorebi::border_manager: invalidating border observer
2026-10-26T23:09:17.924521Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 47907 with notification AXWindowMoved
2026-10-26T23:09:17.927939Z INFO komorebi::border_manager: invalidating border observer
2026-10-26T23:09:17.937888Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 20934 with notification AXWindowMoved
2026-10-26T23:09:17.960135Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 1942 with notification AXWindowMoved
2026-10-26T23:09:17.969092Z INFO process_event: komorebi::process_event: processing event: MoveEnd for process 72441 with notification AXWindowMoved
2026-10-26T23:09:18.001875Z INFO process_event: komorebi::process_event: processing event: FocusChange for process 20934 with notification NSWorkspaceDidActivateApplicationNotification
2026-10-26T23:09:18.008861Z INFO process_event:focus_window{idx=0}: komorebi::container: focusing window
2026-10-26T23:09:18.008881Z INFO process_event:focus_container{idx=0}: komorebi::workspace: focusing container
2026-10-26T23:09:18.018616Z INFO process_event: komorebi::process_event: processing event: FocusChange for process 20934 with notification AXMainWindowChanged
2026-10-26T23:09:18.026372Z INFO process_event:focus_window{idx=0}: komorebi::container: focusing window
2026-10-26T23:09:18.026387Z INFO process_event:focus_container{idx=0}: komorebi::workspace: focusing container
2026-10-26T23:09:18.048765Z INFO process_event: komorebi::process_event: processing event: FocusChange for process 20934 with notification AXApplicationActivated
2026-10-26T23:09:18.052082Z INFO process_event:focus_window{idx=0}: komorebi::container: focusing window
2026-10-26T23:09:18.052094Z INFO process_event:focus_container{idx=0}: komorebi::workspace: focusing container