From f3811fc24ff76025735051a9460465d275c6a8a1 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Wed, 28 Oct 2026 15:49:33 -0700 Subject: [PATCH] feat(time): one clock for every time argument, and no slow handlers that are really delivery delay at, range, frames and locate --utc now read any TimeSpec form (falling back to video timecodes, so existing usage is unchanged). New: logtime:HH:MM:SS[.mmm[uuu]] (also log-time: and wall:HH:MM:SS), a UTC time of day on the session's date, the one inside the recording if it crosses midnight. A bare time of day stays video time. komorebi's own send time (its 'pushed notification' log line) is now lined up with events in order, so an event received long after it was sent still pairs with its handler. Pair gains pushed_mach_ns and delivery_ms, and a handler view shows pushed_video_s and delivery_ms beside the receive time. slow-handler without a push time is info and says it may be delivery delay; a new delivery-batching finding (info) describes notifications delivered in clumps. A bare process_command{Cmd(arg)} span is now read as the command (it was nameless), and commands that differ only in arguments are separate handlers. No cfg(target_os = "macos") code touched. --- docs/usage/investigating-a-recording.md | 14 +- docs/usage/recording-a-bug-repro.md | 3 +- komorebi-recorder/src/analysis/blocks.rs | 178 +++++++++++++++- komorebi-recorder/src/analysis/logparse.rs | 18 ++ komorebi-recorder/src/analysis/overview.rs | 103 ++++++++- komorebi-recorder/src/analysis/timespec.rs | 217 +++++++++++++++++++ komorebi-recorder/src/analysis/trace.rs | 20 +- komorebi-recorder/src/analysis/views.rs | 11 + komorebi-recorder/src/cli/query.rs | 101 +++++++-- komorebi-recorder/src/guide.md | 12 ++ komorebi-recorder/src/report.rs | 49 +++-- komorebi-recorder/src/testkit.rs | 11 + komorebi-recorder/tests/one_clock.rs | 234 +++++++++++++++++++++ 13 files changed, 928 insertions(+), 43 deletions(-) create mode 100644 komorebi-recorder/tests/one_clock.rs diff --git a/docs/usage/investigating-a-recording.md b/docs/usage/investigating-a-recording.md index 55a2eeba..9f4f0004 100644 --- a/docs/usage/investigating-a-recording.md +++ b/docs/usage/investigating-a-recording.md @@ -93,8 +93,14 @@ komorebi-recorder annotate add --kind bug --start 12.5 --end 18 \ komorebi-recorder annotations ``` -Times can be a video timecode (`12.5`, `1:02.5`), `wall:`, `event:`, `log:`, `incident:` or -`bug:` (`.start` or `.end`), each with an offset such as `+3s`. `event:12` is when komorebi began handling event 12 +Times can be a video timecode (`12.5`, `1:02.5`), `logtime:`, `wall:`, `mach:`, +`event:`, `log:`, `incident:` or `bug:` (`.start` or `.end`), each with an offset such as `+3s`. Every +command that takes a time (`at`, `range`, `frames`, `trace`, `diff`, `events`, ...) takes all of them. + +`logtime:15:46:22.743` is a time of day as komorebi's log writes it (UTC), so a log line can be quoted as it is; the +date comes from the recording (the one on which the time falls inside it, if the recording crosses midnight). +`wall:15:46:22.743` means the same. It needs the prefix because a bare `1:02:03` is video time, and the two cannot be +told apart by their digits. `event:12` is when komorebi began handling event 12 and `event:12.end` when it finished. ## Commands @@ -138,6 +144,10 @@ the same. - The event timestamp is when komorebi finished the handler. Time spent waiting for its lock or in accessibility calls before the handler's first log line is invisible, so `handler_ms` is a lower bound. +- The recorder can receive notifications long after komorebi sent them, and in clumps. komorebi's own send time is its + `pushed notification to subscriber:` DEBUG line; `events --json` shows it as `pushed_video_s` next to the received + `video_s`, with `delivery_ms` between them, and `overview` reports a `delivery-batching` finding (info) instead of a + slow handler. A `slow-handler` finding in a log without push lines is marked as possibly delivery delay. - At the default `info` level there is no log line for the end of an event handler, and few for the decisions inside it. Start komorebi with `--log-level trace` before recording a bug you intend to investigate. - The `rect` of a window in the state is read live from the accessibility API when the state is serialized: it is where diff --git a/docs/usage/recording-a-bug-repro.md b/docs/usage/recording-a-bug-repro.md index d3f816d7..69806fa8 100644 --- a/docs/usage/recording-a-bug-repro.md +++ b/docs/usage/recording-a-bug-repro.md @@ -186,7 +186,8 @@ session. ## Asking questions of a session -Times are video timecodes: `12.5`, `00:12.500` or `1:02:03`. Video `00:00.000` is the first captured frame. +Times are video timecodes: `12.5`, `00:12.500` or `1:02:03`, or a time from komorebi's log such as +`logtime:15:46:22.743` (UTC), or `wall:...`, `event:12`. Video `00:00.000` is the first captured frame. ``` # everything within +-1s of 12.5s, grouped by source diff --git a/komorebi-recorder/src/analysis/blocks.rs b/komorebi-recorder/src/analysis/blocks.rs index 4eeeaea4..e74c92b9 100644 --- a/komorebi-recorder/src/analysis/blocks.rs +++ b/komorebi-recorder/src/analysis/blocks.rs @@ -70,6 +70,7 @@ use super::flavor::BlockHeader; use super::flavor::Rules; use super::logparse::Level; use super::logparse::Line; +use super::logparse::Span; use crate::clock::ClockMap; use schemars::JsonSchema; use serde::Serialize; @@ -189,13 +190,28 @@ pub fn build(lines: &[Line], clock: &ClockMap, rules: &dyn Rules) -> Vec let mut blocks: Vec = Vec::new(); let mut open: Option = None; + // the root span a command block was opened with, to tell two commands of the same name apart + let mut command_span: Option<&Span> = 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])) { + let mut header = rules.block_header(line, open.map(|index| &blocks[index])); + // a command that failed leaves its block open, and the next command of the same name, with + // other arguments, is another handler + if header.is_none() + && line.root_span() == Some("process_command") + && open.is_some_and(|index| blocks[index].kind == BlockKind::Command) + && command_span.is_some_and(|span| line.spans.first() != Some(span)) + { + header = rules.block_header(line, None); + } + if let Some(header) = header { + if header.kind == BlockKind::Command { + command_span = line.spans.first(); + } blocks.push(new_block(blocks.len(), header, line.number, time)); open = Some(blocks.len() - 1); continue; @@ -289,8 +305,20 @@ pub struct Pair { 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. + /// When komorebi logged handing this notification to the recorder, on the master clock in + /// nanoseconds: komorebi's own send time, as opposed to the receive time in `events.jsonl`. + /// `None` when the log has no such line for this event. + #[serde(default)] + pub pushed_mach_ns: Option, + /// Milliseconds from komorebi sending the notification (`pushed_mach_ns`) to the recorder + /// receiving it. Near 0 normally; a large value means the notification sat in a socket or a + /// queue, which is delivery delay and not komorebi's doing. `None` when the send time is not + /// known. + #[serde(default)] + pub delivery_ms: Option, + /// Milliseconds the handler took, at least. From its header to the push when the push is known + /// and was not received at once (so that delivery delay is not counted as handling), otherwise + /// from its header to the event being received. pub handler_ms: Option, } @@ -302,6 +330,58 @@ 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; +/// The longest a notification is believed to sit between komorebi sending it and the recorder +/// receiving it, when lining pushes up with events in order. A push further back than this is not +/// taken for the event's. +const MAX_DELIVERY_NS: u64 = 30_000_000_000; + +/// How many pushes may be skipped to find the one an event matches, when lining them up in order +/// (a notification the recorder did not keep leaves one over). +const ALIGN_LOOKAHEAD: usize = 3; + +/// Lines komorebi's pushes to `subscriber` up with the events, in order. +/// +/// komorebi sends to a subscriber over one socket, so the notifications arrive in the order they +/// were pushed: the first event received is the first push logged, and so on. That identifies the +/// push, and so the handler, of an event even when it was received long after it was sent, which +/// the 100 ms window of [`Quality::Pushed`] cannot. A push is taken for an event when it was +/// logged no later than the event was received (with slack), no more than 30 s before it, and its +/// block has the event's name; up to three pushes may be skipped to get there. Returns, for each +/// event, the block id and the push, or `None`. +fn align<'a>( + events: &[EventRecord], + blocks: &'a [Block], + subscriber: Option<&str>, +) -> Vec> { + let Some(name) = subscriber else { + return vec![None; events.len()]; + }; + + let mut pushes: Vec<(usize, &Push)> = blocks + .iter() + .flat_map(|block| block.pushes.iter().map(move |push| (block.id, push))) + .filter(|(_, push)| push.subscriber == name) + .collect(); + pushes.sort_by_key(|(_, push)| push.line); + + let mut next = 0; + events + .iter() + .map(|event| { + let found = (next..pushes.len().min(next + 1 + ALIGN_LOOKAHEAD)).find(|index| { + let (block, push) = pushes[*index]; + push.mach_ns <= event.recv_mach_ns.saturating_add(SLACK_NS) + && event.recv_mach_ns.saturating_sub(push.mach_ns) <= MAX_DELIVERY_NS + && blocks[block].name == event.info.name + }); + found.map(|index| { + next = index + 1; + pushes[index] + }) + }) + .collect() +} + /// 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. /// @@ -383,6 +463,13 @@ fn push_for<'a>( /// 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. /// +/// With a `subscriber`, the pushes to it are also lined up with the events in order, because +/// komorebi sends over one socket and the notifications arrive in the order they were pushed. That +/// pairs an event with its handler even when the recorder received it long after komorebi sent it +/// (notifications are sometimes delivered in clumps), and gives [`Pair::pushed_mach_ns`] and +/// [`Pair::delivery_ms`]. Such a pair's `handler_ms` ends at the push, not at the receipt, so that +/// delivery delay is not counted as handling. +/// /// # Performance /// /// Each event looks at every block, so the cost grows with events times blocks. @@ -445,10 +532,38 @@ pub fn pair(events: &[EventRecord], blocks: &[Block], subscriber: Option<&str>) let mut previous_recv = 0_u64; let mut pairs = Vec::with_capacity(events.len()); - for event in events { + // the pushes that line up with an event in order claim their blocks first + let aligned = align(events, blocks, subscriber); + for (block, _) in aligned.iter().flatten() { + used[*block] = true; + } + + for (event, aligned) in events.iter().zip(aligned) { let upper = event.recv_mach_ns.saturating_add(SLACK_NS); let lower = previous_recv.saturating_sub(SLACK_NS); + if let Some((id, push)) = aligned { + let delivery_ns = event.recv_mach_ns.saturating_sub(push.mach_ns); + // a notification received long after it was sent says nothing about the handler: count + // the handler until komorebi sent it + let until = if delivery_ns > PUSH_WINDOW_NS { + push.mach_ns + } else { + event.recv_mach_ns + }; + pairs.push(Pair { + seq: event.seq, + block: Some(id), + quality: Quality::Pushed, + pushed_line: Some(push.line), + pushed_mach_ns: Some(push.mach_ns), + delivery_ms: Some(delivery_ns as f64 / 1e6), + handler_ms: Some(until.saturating_sub(blocks[id].header_mach_ns) as f64 / 1e6), + }); + previous_recv = event.recv_mach_ns; + continue; + } + let wanted = match event.info.family { Family::WindowManager => Some(BlockKind::Event), Family::Command => Some(BlockKind::Command), @@ -493,6 +608,9 @@ pub fn pair(events: &[EventRecord], blocks: &[Block], subscriber: Option<&str>) Quality::Header }, pushed_line: push.map(|push| push.line), + pushed_mach_ns: push.map(|push| push.mach_ns), + delivery_ms: push + .map(|push| event.recv_mach_ns.saturating_sub(push.mach_ns) as f64 / 1e6), handler_ms: Some( event.recv_mach_ns.saturating_sub(block.header_mach_ns) as f64 / 1e6, ), @@ -503,6 +621,8 @@ pub fn pair(events: &[EventRecord], blocks: &[Block], subscriber: Option<&str>) block: None, quality: Quality::None, pushed_line: None, + pushed_mach_ns: None, + delivery_ms: None, handler_ms: None, } }; @@ -827,4 +947,54 @@ mod tests { "most handler lines are in a block" ); } + + #[test] + fn notifications_received_late_are_lined_up_with_their_pushes_in_order() { + let push = + "process_event: komorebi: pushed notification to subscriber: komorebi-recorder-1"; + let lines = log(&[ + (1.0, "INFO", HEADER), + (1.005, "DEBUG", push), + (2.0, "INFO", HEADER), + (2.005, "DEBUG", push), + ]); + let blocks = build(&lines, &clock(), Flavor::Macos.rules()); + // both are received together at 5 s: the second block is not "the latest before receipt" + let events = vec![event(1, 5.000, move_end(10)), event(2, 5.001, move_end(10))]; + + let pairs = pair(&events, &blocks, Some("komorebi-recorder-1")); + assert_eq!(pairs[0].block, Some(0)); + assert_eq!(pairs[1].block, Some(1)); + for pair in &pairs { + assert_eq!(pair.quality, Quality::Pushed); + assert!((pair.handler_ms.expect("handler") - 5.0).abs() < 0.01); + } + assert!((pairs[0].delivery_ms.expect("delivery") - 3995.0).abs() < 0.01); + assert_eq!(pairs[1].pushed_mach_ns, Some(testkit::mach_ns(2.005))); + + // without the subscriber, nothing says when komorebi sent them + let unpushed = pair(&events, &blocks, None); + assert_eq!(unpushed[0].quality, Quality::Header); + assert_eq!(unpushed[0].pushed_mach_ns, None); + } + + #[test] + fn a_push_for_an_event_that_was_not_recorded_is_skipped() { + let push = + "process_event: komorebi: pushed notification to subscriber: komorebi-recorder-1"; + let focus = "process_event: komorebi::process_event: processing event: FocusChange for process 11 with notification AXApplicationActivated"; + let lines = log(&[ + (1.0, "INFO", focus), + (1.005, "DEBUG", push), + (2.0, "INFO", HEADER), + (2.005, "DEBUG", push), + ]); + let blocks = build(&lines, &clock(), Flavor::Macos.rules()); + // the recorder missed the first notification + let events = vec![event(1, 2.01, move_end(10))]; + + let pairs = pair(&events, &blocks, Some("komorebi-recorder-1")); + assert_eq!(pairs[0].block, Some(1)); + assert_eq!(pairs[0].quality, Quality::Pushed); + } } diff --git a/komorebi-recorder/src/analysis/logparse.rs b/komorebi-recorder/src/analysis/logparse.rs index 62528d05..c7de825e 100644 --- a/komorebi-recorder/src/analysis/logparse.rs +++ b/komorebi-recorder/src/analysis/logparse.rs @@ -292,6 +292,11 @@ fn braced(text: &str) -> Option<(&str, &str)> { fn parse_fields(text: &str) -> Vec<(String, String)> { let mut fields = Vec::new(); let mut rest = text.trim(); + // komorebi for Windows writes a command's span as `process_command{FocusWindow(Left)}`, a bare + // value with no field name: keep it as the `message` field the flavor's rules read + if !rest.is_empty() && !rest.contains('=') { + return vec![("message".to_string(), rest.to_string())]; + } while !rest.is_empty() { let Some((key, after)) = rest.split_once('=') else { break; @@ -615,4 +620,17 @@ mod tests { assert_eq!(without_level, 0); assert!(without_target * 1000 <= structured.len()); } + + #[test] + fn a_span_with_a_bare_value_is_its_message() { + let parsed = parse( + b"2026-10-28T15:46:20.730173Z INFO process_command{FocusWindow(Left)}: komorebi::process_command: processed +", + ); + let fields = &parsed[0].spans[0].fields; + assert_eq!( + fields, + &[("message".to_string(), "FocusWindow(Left)".to_string())] + ); + } } diff --git a/komorebi-recorder/src/analysis/overview.rs b/komorebi-recorder/src/analysis/overview.rs index 9a1f9987..398df74b 100644 --- a/komorebi-recorder/src/analysis/overview.rs +++ b/komorebi-recorder/src/analysis/overview.rs @@ -21,7 +21,8 @@ //! | `window-flapping` | one window's hidden state flipping (parked in komorebi's hiding position, or brought back) at least 4 times within 10 s | warn | //! | `focus-oscillation` | focus changing at least 4 times within 5 s between at most two windows | warn | //! | `event-storm` | 20 or more events within 1 s | warn for 60 or more, else info | -//! | `slow-handler` | a handler that took at least 250 ms from its header to its notification: the 10 slowest | warn for 1 s or more, else info | +//! | `slow-handler` | a handler that took at least 250 ms from its header to komorebi sending its notification (or, with no `pushed notification` line to say when, to the recorder receiving it): the 10 slowest | warn for 1 s or more when komorebi's own send time confirms it; info otherwise, and the text then says it may be delivery delay | +//! | `delivery-batching` | three or more events received within 50 ms of each other that komorebi sent over 250 ms or more: the notifications were queued before the recorder got them, which is not a slow handler | info | //! | `monitor-churn` | two or more display notifications, each within 5 s of the first | warn | //! | `log-error`, `log-warning` | komorebi log lines at `ERROR` or `WARN`: one finding for each module and message, where messages that differ only in digits are the same | warn for `log-error`, info for `log-warning` | //! | `incident:` | something the recorder noted about the machine: a display plugged or unplugged, a sleep, a capture that failed | warn for `capture-failed`, `log-stream-lost` and `komorebi-exited`, else info | @@ -42,6 +43,7 @@ //! ([`Rules::slow_handler_cause`](super::flavor::Rules::slow_handler_cause)). use super::Analysis; +use super::blocks::Quality; use super::classify::Class; use super::events::Family; use super::invariants; @@ -77,7 +79,7 @@ pub const PRE_ROLL_NS: u64 = 10_000_000_000; pub struct Finding { /// `invariant:` (including the ones read from Windows' own account of a window when the /// recording was made with `--probe-windows`), `window-flapping`, `focus-oscillation`, - /// `event-storm`, `slow-handler`, `log-error`, `log-warning`, `monitor-churn` or + /// `event-storm`, `slow-handler`, `delivery-batching`, `log-error`, `log-warning`, `monitor-churn` or /// `incident:`. pub kind: String, /// How serious it is. For an `invariant:` finding it is the violation's, lowered one step if it @@ -732,18 +734,28 @@ impl Analysis { slow.sort_by(|a, b| b.1.total_cmp(&a.1)); for (index, ms) in slow.into_iter().take(10) { let event = &events[index]; + // only a pairing with komorebi's own send time measures the handler: otherwise the + // time is up to the recorder receiving the notification, which a queue can delay + let exact = pairing.pairs[index].quality == Quality::Pushed; + let cause = self.flavor().rules().slow_handler_cause(); let mut finding = self.finding( "slow-handler", - if ms >= 1000.0 { + if exact && ms >= 1000.0 { Severity::Warn } else { Severity::Info }, - format!( - "{} took at least {ms:.0} ms to handle: {}", - event.info.summary(), - self.flavor().rules().slow_handler_cause() - ), + if exact { + format!( + "{} took at least {ms:.0} ms to handle: {cause}", + event.info.summary() + ) + } else { + format!( + "{} was received {ms:.0} ms after its handler began. This may be delivery delay (the notification was queued before the recorder got it) and not komorebi being slow, because the log has no push time to tell them apart. If komorebi was slow: {cause}", + event.info.summary() + ) + }, event.recv_mach_ns.saturating_sub((ms * 1e6) as u64), event.recv_mach_ns, ); @@ -752,6 +764,8 @@ impl Analysis { found.push(finding); } + self.find_delivery_batching(found); + // display changes arriving together let monitor: Vec = (0..events.len()) .filter(|index| events[*index].info.family == Family::Monitor) @@ -794,6 +808,79 @@ impl Analysis { let _ = Class::Echo; } + /// Notifications that komorebi sent over a stretch of time but the recorder received together. + /// + /// A run of at least three events received within 50 ms of each other whose send times (the + /// `pushed notification` line, else the handler's header) are spread over at least 250 ms was + /// delivered in a batch. The delay is between komorebi and the recorder, so it is not a slow + /// handler, and the log times, not the receive times, say when komorebi acted. + fn find_delivery_batching(&self, found: &mut Vec) { + let events = self.events(); + let pairing = self.pairing(); + let dir = self.session.dir.display().to_string(); + let log = self.log(); + + // when komorebi sent (or at least began handling) each event, where the log says + let sent = |index: usize| -> Option<(u64, bool)> { + let pair = &pairing.pairs[index]; + pair.pushed_mach_ns.map(|ns| (ns, true)).or_else(|| { + pair.block + .and_then(|id| log.blocks.get(id)) + .map(|block| (block.header_mach_ns, false)) + }) + }; + + let mut start = 0; + while start < events.len() { + let mut stop = start; + while stop + 1 < events.len() + && events[stop + 1].recv_mach_ns - events[stop].recv_mach_ns <= 50_000_000 + { + stop += 1; + } + + let times: Vec<(u64, bool)> = (start..=stop).filter_map(sent).collect(); + let known = times.len(); + let earliest = times.iter().map(|(ns, _)| *ns).min(); + let latest = times.iter().map(|(ns, _)| *ns).max(); + if let (true, Some(earliest), Some(latest)) = (known >= 3, earliest, latest) + && latest - earliest >= 250_000_000 + { + let (first, last) = (&events[start], &events[stop]); + let by_push = times.iter().all(|(_, pushed)| *pushed); + let behind = last.recv_mach_ns.saturating_sub(earliest) as f64 / 1e3; + let mut finding = self.finding( + "delivery-batching", + Severity::Info, + format!( + "{} events were received within {:.0} ms of each other, but {} sent them over {:.1} s, the first {:.1} s before they were received. This is delivery delay between komorebi and the recorder, not slow handlers: go by the log's times (a handler's `pushed_video_s` in `events --json`) for when komorebi acted, not by the received times", + stop - start + 1, + last.recv_mach_ns.saturating_sub(first.recv_mach_ns) as f64 / 1e6, + if by_push { + "komorebi's own log shows it" + } else { + "the handler headers in komorebi's log show it" + }, + (latest - earliest) as f64 / 1e9, + behind / 1e6, + ), + earliest, + last.recv_mach_ns, + ); + finding.refs = vec![ + format!("event:{}", first.seq), + format!("event:{}", last.seq), + ]; + finding.next = Some(format!( + "komorebi-recorder events {dir} --from event:{} --to event:{}", + first.seq, last.seq + )); + found.push(finding); + } + start = stop + 1; + } + } + fn find_log_problems(&self, found: &mut Vec) { #[derive(Default)] struct Group { diff --git a/komorebi-recorder/src/analysis/timespec.rs b/komorebi-recorder/src/analysis/timespec.rs index 39f07a62..21d199e2 100644 --- a/komorebi-recorder/src/analysis/timespec.rs +++ b/komorebi-recorder/src/analysis/timespec.rs @@ -4,6 +4,7 @@ //! |---|---| //! | `12.5`, `1:02.5`, `-1.5` | video time, see [`crate::timecode`] | //! | `wall:2026-10-26T20:00:00Z` | a UTC time (RFC 3339) | +//! | `logtime:15:46:22.743`, `wall:15:46:22.743` | a UTC time of day, as komorebi's log writes it, on the session's date | //! | `mach:123456789` | the recorder's master clock, in nanoseconds | //! | `event:12`, `log:345`, `incident:2` | when that record happened | //! | `bug:a-3f9c1e02`, `bug:a-3f9c1e02.start`, `bug:a-3f9c1e02.end` | an annotation's start or end | @@ -14,6 +15,21 @@ //! suffix is accepted after any item reference, but only an event and an annotation have two edges: //! on a log line or an incident it changes nothing. //! +//! # Log time +//! +//! komorebi's log timestamps are UTC, and a log line is a natural thing to quote: `logtime:15:46:22.743` +//! (`log-time:` is the same) names that time of day, `HH:MM:SS` with an optional fraction of 1 to 6 +//! digits (milliseconds, or microseconds). `wall:` followed by a time of day instead of an RFC 3339 +//! time (`wall:15:46:22.743`) means the same. It needs no date: it is taken from the session, on the +//! date the recording started, and if the recording crosses midnight UTC, on the date on which the +//! time falls inside the recording. A time of day outside the recording is placed on the date +//! nearest to it, so a log line from just before the recording began is just before it. +//! +//! A bare `15:46:22.743` is never a log time: it is video time, `1:02:03` is one hour, two minutes +//! and three seconds into the video, and a time of day is not told apart from that by its digits (a +//! recording can be two hours long, and `01:02:03` is both). So log time always has its prefix, and +//! a prefix never changes what a name without one means. +//! //! Resolving a name never guesses: an unknown event, a log line without a timestamp or an //! annotation that does not exist is an error with the "not found" exit code. The one exception is //! an annotation whose end was never set, which ends when the recording did. @@ -67,6 +83,8 @@ use crate::clock::ClockMap; use crate::session::Manifest; use crate::timecode; use chrono::DateTime; +use chrono::NaiveTime; +use chrono::Timelike; use chrono::Utc; use color_eyre::eyre; use std::str::FromStr; @@ -92,6 +110,9 @@ pub enum Anchor { Video(f64), /// A UTC time (`wall:...`), mapped to the master clock through the session's clock anchors. Wall(DateTime), + /// A UTC time of day with no date (`logtime:15:46:22.743`, `wall:15:46:22.743`): komorebi's log + /// timestamps without the day. [`TimeSpec::resolve`] gives it the session's date. + TimeOfDay(NaiveTime), /// A reading of the master clock in nanoseconds (`mach:...`). Mach(u64), /// When a recorded item happened: an event, a log line, an incident or an annotation. `edge` @@ -117,6 +138,8 @@ pub enum Anchor { /// - the text is empty or only whitespace: `an empty time`; /// - a `wall:` time is not RFC 3339: `'': expected an RFC 3339 time like /// wall:2026-10-26T19:43:35.062613Z`; +/// - a `logtime:` (or `log-time:`) time is not `HH:MM:SS` with an optional fraction of 1 to 6 +/// digits: `'': expected a UTC time of day like logtime:15:46:22.743`; /// - a `mach:` time is not a whole number of nanoseconds: `'': mach: takes nanoseconds, e.g. /// mach:123456`; /// - the text starts like an item reference (`event:`, `log:`, `incident:`, `ann:`, `bug:`, @@ -137,6 +160,11 @@ pub enum Anchor { /// /// // an offset needs a unit, so this is not an offset and not a timecode /// assert!("12.5+3".parse::().is_err()); +/// +/// // a time of day as komorebi's log writes it needs its prefix: without it, this is video time +/// let spec: TimeSpec = "logtime:15:46:22.743+1s".parse()?; +/// assert!(matches!(spec.anchor, Anchor::TimeOfDay(_))); +/// assert_eq!("1:02:03".parse::()?.anchor, Anchor::Video(3723.0)); /// # Ok::<(), Box>(()) /// ``` #[derive(Debug, Clone, PartialEq)] @@ -298,8 +326,61 @@ fn split_offset(text: &str) -> (&str, f64) { (text, 0.0) } +/// Reads `HH:MM:SS` with an optional fraction of 1 to 6 digits. +fn parse_time_of_day(text: &str) -> Option { + let (clock, fraction) = match text.split_once('.') { + Some((clock, fraction)) => (clock, Some(fraction)), + None => (text, None), + }; + + let mut parts = clock.split(':'); + let (hours, minutes, seconds) = (parts.next()?, parts.next()?, parts.next()?); + if parts.next().is_some() { + return None; + } + + let number = |part: &str, width: std::ops::RangeInclusive| { + (width.contains(&part.len()) && part.bytes().all(|byte| byte.is_ascii_digit())) + .then(|| part.parse::().ok()) + .flatten() + }; + let micros = match fraction { + None => 0, + Some(digits) => { + let value = number(digits, 1..=6)?; + // `.5` is half a second, not five microseconds + value * 10_u32.pow(6 - u32::try_from(digits.len()).ok()?) + } + }; + + NaiveTime::from_hms_micro_opt( + number(hours, 1..=2)?, + number(minutes, 2..=2)?, + number(seconds, 2..=2)?, + micros, + ) +} + fn parse_anchor(head: &str, original: &str) -> eyre::Result { + if let Some(rest) = head + .strip_prefix("logtime:") + .or_else(|| head.strip_prefix("log-time:")) + { + return parse_time_of_day(rest) + .map(Anchor::TimeOfDay) + .ok_or_else(|| { + envelope::usage(format!( + "'{original}': expected a UTC time of day like logtime:15:46:22.743" + )) + }); + } + if let Some(rest) = head.strip_prefix("wall:") { + // `wall:15:46:22.743` is a time of day; anything else is read as RFC 3339 + if let Some(time) = parse_time_of_day(rest) { + return Ok(Anchor::TimeOfDay(time)); + } + let time = DateTime::parse_from_rfc3339(rest).map_err(|_| { envelope::usage(format!( "'{original}': expected an RFC 3339 time like wall:2026-10-26T19:43:35.062613Z" @@ -400,6 +481,9 @@ impl TimeSpec { Anchor::Wall(time) => ClockMap::new(manifest.anchors.clone()) .wall_to_mach(time.timestamp_micros()) .ok_or_else(|| envelope::unusable("the session has no clock anchors"))?, + Anchor::TimeOfDay(time) => ClockMap::new(manifest.anchors.clone()) + .wall_to_mach(session_wall_us(*time, manifest)) + .ok_or_else(|| envelope::unusable("the session has no clock anchors"))?, Anchor::Item { item, edge } => match item { ItemRef::Event(seq) => lookup.event_mach_ns(*seq, *edge)?, ItemRef::Log(line) => lookup.log_mach_ns(*line)?, @@ -424,6 +508,29 @@ impl TimeSpec { } } +/// Returns the wall-clock time, in microseconds since the epoch, of UTC time of day `time` on the +/// date that suits the session: the date on which it falls inside the recording (the recording can +/// cross midnight), or else the date on which it is nearest to the recording. +fn session_wall_us(time: NaiveTime, manifest: &Manifest) -> i64 { + const DAY_US: i64 = 86_400_000_000; + + let first = manifest.start.wall_us; + let last = manifest + .stop + .map(|stop| stop.wall_us) + .into_iter() + .chain(manifest.anchors.iter().map(|anchor| anchor.wall_us)) + .fold(first, i64::max); + let of_day = i64::from(time.num_seconds_from_midnight()) * 1_000_000 + + i64::from(time.nanosecond() / 1000); + + (first.div_euclid(DAY_US) - 1..=last.div_euclid(DAY_US) + 1) + .map(|day| day * DAY_US + of_day) + // how far outside the recording: 0 inside it + .min_by_key(|wall_us| (first - wall_us).max(wall_us - last).max(0)) + .unwrap_or(first) +} + /// Returns when the recording ended on the master clock, in nanoseconds. /// /// That is the manifest's `stop`, else when video capture ended, else when the recording started. @@ -594,6 +701,116 @@ mod tests { } } + #[test] + fn a_log_time_is_a_utc_time_of_day_on_the_sessions_date() { + // wall 5 s after the epoch is 4 s into the video + for text in [ + "logtime:00:00:05", + "log-time:00:00:05.000", + "wall:00:00:05", + "logtime:0:00:05.0", + ] { + let resolved = resolve(text).expect(text); + assert!(close(resolved.video_s, 4.0), "{text}"); + } + assert!(close( + resolve("logtime:00:00:05.250").expect("ms").video_s, + 4.25 + )); + assert!(close( + resolve("logtime:00:00:05.000250").expect("us").video_s, + 4.00025 + )); + assert!(close( + resolve("logtime:00:00:05+2s").expect("offset").video_s, + 6.0 + )); + assert!(close( + resolve("wall:00:00:05-500ms").expect("offset").video_s, + 3.5 + )); + } + + #[test] + fn a_bare_time_of_day_is_still_video_time() { + assert_eq!( + "1:02:03".parse::().expect("clock").anchor, + Anchor::Video(3723.0) + ); + assert_eq!( + "1:02.5".parse::().expect("minutes").anchor, + Anchor::Video(62.5) + ); + assert_eq!( + "12.5".parse::().expect("seconds").anchor, + Anchor::Video(12.5) + ); + assert!(matches!( + "wall:2026-10-26T20:00:00Z" + .parse::() + .expect("rfc") + .anchor, + Anchor::Wall(_) + )); + } + + #[test] + fn malformed_log_times_are_usage_errors() { + for text in [ + "logtime:", + "logtime:12:00", + "logtime:25:00:00", + "logtime:12:60:00", + "logtime:12:00:00.", + "logtime:12:00:00.1234567", + "logtime:12:00:00:00", + "logtime:noon", + "wall:12:00:99", + ] { + let error = text.parse::().expect_err(text); + assert_eq!( + envelope::exit_kind(&error), + envelope::ExitKind::Usage, + "{text}" + ); + } + } + + #[test] + fn a_log_time_takes_the_date_on_which_it_falls_inside_a_recording_that_crosses_midnight() { + let day = 86_400_000_000_i64; + let start = 20_000 * day + (23 * 3600 + 59 * 60 + 50) * 1_000_000; + let mut manifest = Manifest::new( + Moment { + mach_ns: 100_000_000_000, + wall_us: start, + }, + vec![ClockAnchor { + mach_ns: 100_000_000_000, + wall_us: start, + }], + ); + manifest.video_t0_mach_ns = Some(100_000_000_000); + manifest.stop = Some(Moment { + mach_ns: 130_000_000_000, + wall_us: start + 30_000_000, + }); + let video = |text: &str| { + text.parse::() + .and_then(|spec| spec.resolve(&manifest, &Fake)) + .expect(text) + .video_s + }; + + // before midnight: the day the recording started + assert!(close(video("logtime:23:59:55"), 5.0)); + // after midnight: the next day, which is inside the recording + assert!(close(video("logtime:00:00:05"), 15.0)); + // outside the recording, the nearest date: a minute before and a minute after + assert!(close(video("logtime:23:58:50"), -60.0)); + assert!(close(video("logtime:00:01:10"), 80.0)); + } + #[test] fn times_before_the_clock_started_clamp_to_zero() { let resolved = resolve("mach:5-9s").expect("clamped"); diff --git a/komorebi-recorder/src/analysis/trace.rs b/komorebi-recorder/src/analysis/trace.rs index e8bd3ca9..02dc5198 100644 --- a/komorebi-recorder/src/analysis/trace.rs +++ b/komorebi-recorder/src/analysis/trace.rs @@ -432,14 +432,28 @@ impl Analysis { }; if let Some(block) = block { - if let Some(ms) = pair.handler_ms + if let Some(ms) = pair.delivery_ms && ms >= 100.0 { notes.push(format!( - "the handler took at least {ms:.0} ms from its header to the notification: {}", - self.flavor().rules().slow_handler_cause() + "komorebi sent this notification {ms:.0} ms before the recorder received it: that is delivery delay (it was queued), not the handler being slow. Go by the pushed time, not the received time, for when komorebi acted" )); } + if let Some(ms) = pair.handler_ms + && ms >= 100.0 + { + if pair.quality == super::blocks::Quality::Pushed { + notes.push(format!( + "the handler took at least {ms:.0} ms from its header to the notification: {}", + self.flavor().rules().slow_handler_cause() + )); + } else { + notes.push(format!( + "the notification was received {ms:.0} ms after the handler's header. That may be delivery delay and not komorebi being slow, because the log has no push time to tell them apart. If komorebi was slow: {}", + self.flavor().rules().slow_handler_cause() + )); + } + } if block.errors + block.warnings > 0 { notes.push(format!( "the handler logged {} error(s) and {} warning(s)", diff --git a/komorebi-recorder/src/analysis/views.rs b/komorebi-recorder/src/analysis/views.rs index 833ad7cb..99a84858 100644 --- a/komorebi-recorder/src/analysis/views.rs +++ b/komorebi-recorder/src/analysis/views.rs @@ -39,6 +39,15 @@ pub struct HandlerView { pub started_video_s: f64, /// At least how long the handler took, in milliseconds: header to the event being received. pub handler_ms: Option, + /// When komorebi logged sending the notification (its `pushed notification to subscriber` + /// line), in video time: komorebi's own send time, next to the `video_s` the recorder received + /// it at. Absent when the log has no such line for the event. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub pushed_video_s: Option, + /// Milliseconds between komorebi sending the notification and the recorder receiving it. A + /// large value is delivery delay (the notification was queued), not komorebi being slow. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub delivery_ms: Option, /// How many log lines the handler logged, header included. pub lines: usize, /// How many of those lines are at level ERROR. @@ -112,6 +121,8 @@ impl Analysis { last_line: block.last_line, started_video_s: self.video_s(block.header_mach_ns), handler_ms: pair.handler_ms, + pushed_video_s: pair.pushed_mach_ns.map(|ns| self.video_s(ns)), + delivery_ms: pair.delivery_ms, lines: block.lines.len(), errors: block.errors, warnings: block.warnings, diff --git a/komorebi-recorder/src/cli/query.rs b/komorebi-recorder/src/cli/query.rs index d665f318..9f16d05f 100644 --- a/komorebi-recorder/src/cli/query.rs +++ b/komorebi-recorder/src/cli/query.rs @@ -2,7 +2,9 @@ //! //! These read the session's timeline directly (see [`crate::timeline`]), not through an `Analysis`, //! so they say what was recorded without interpreting it as the output of one komorebi or the -//! other. Times are video timecodes ([`crate::timecode`]). +//! other. A time is a video timecode ([`crate::timecode`]) or any other form of +//! [`TimeSpec`](crate::analysis::timespec::TimeSpec): `logtime:15:46:22.743`, `wall:...`, `mach:...`, +//! `event:12`, `bug:...`, with an offset such as `+3s`. //! //! | Command | Asks | Prints | //! |---|---|---| @@ -23,6 +25,11 @@ use super::limit; use super::load; use super::print_json; +use crate::analysis::Analysis; +use crate::analysis::timespec::Anchor; +use crate::analysis::timespec::Edge; +use crate::analysis::timespec::Lookup; +use crate::analysis::timespec::TimeSpec; use crate::frames; use crate::report; use crate::timecode; @@ -69,7 +76,7 @@ impl FilterArgs { pub struct AtArgs { /// Session directory pub session: PathBuf, - /// Video timecode: 12.5, 00:12.500 or 1:02:03 + /// Video timecode (12.5, 00:12.500, 1:02:03), or logtime:15:46:22.743, wall:..., event:12, ... pub time: String, /// How far either side of the timecode to look #[arg(long, default_value = "1s")] @@ -84,9 +91,9 @@ pub struct AtArgs { pub struct RangeArgs { /// Session directory pub session: PathBuf, - /// Start timecode + /// Start: a video timecode, or logtime:15:46:22.743, wall:..., event:12, ... pub from: String, - /// End timecode + /// End: the same forms pub to: String, /// What to look at, and how to print it #[command(flatten)] @@ -121,7 +128,8 @@ pub struct SummaryArgs { pub struct LocateArgs { /// Session directory pub session: PathBuf, - /// A UTC time (RFC 3339), e.g. 2026-10-26T19:43:35.062613Z + /// A UTC time (RFC 3339), e.g. 2026-10-26T19:43:35.062613Z, or a time of day from the log, + /// e.g. logtime:15:46:22.743 #[arg(long, group = "what")] pub utc: Option, /// A 1-based line number in the session's komorebi.log @@ -183,9 +191,61 @@ fn hint_unknown_app(manifest: &crate::session::Manifest, filter: &FilterArgs, em } } +/// A lookup for names that point at nothing in the session: `event:12` is not understood here, and +/// `time_arg` opens the whole analysis for those instead. +struct NoItems; + +impl NoItems { + fn refuse() -> eyre::Result { + Err(crate::analysis::envelope::usage( + "this time names an item of the session", + )) + } +} + +impl Lookup for NoItems { + fn event_mach_ns(&self, _: u64, _: Edge) -> eyre::Result { + Self::refuse() + } + fn log_mach_ns(&self, _: u64) -> eyre::Result { + Self::refuse() + } + fn incident_mach_ns(&self, _: u64) -> eyre::Result { + Self::refuse() + } + fn annotation_span(&self, _: &str) -> eyre::Result<(u64, Option)> { + Self::refuse() + } +} + +/// Reads a time argument as seconds of video time. +/// +/// Any [`TimeSpec`] is accepted: a video timecode (which is read exactly as [`timecode::parse`] +/// reads it, so existing usage is unchanged), a log time, `wall:`, `mach:`, and the names of events, +/// log lines, incidents and annotations, each with an optional offset. What does not parse as a +/// `TimeSpec` is tried as a timecode before giving up, and the `TimeSpec` error, which says what the +/// forms are, is the one reported. +fn time_arg( + text: &str, + dir: &std::path::Path, + manifest: &crate::session::Manifest, +) -> eyre::Result { + let spec = match text.parse::() { + Ok(spec) => spec, + Err(error) => return timecode::parse(text).map_err(|_| error), + }; + + match spec.anchor { + // no clamping or round trip through the master clock: the same number as ever + Anchor::Video(seconds) => Ok(seconds + spec.offset_s), + Anchor::Item { .. } => Ok(Analysis::open(dir)?.resolve(text)?.video_s), + _ => Ok(spec.resolve(manifest, &NoItems)?.video_s), + } +} + pub(super) fn at(args: &AtArgs) -> eyre::Result<()> { let (session, manifest) = load(&args.session)?; - let center = timecode::parse(&args.time)?; + let center = time_arg(&args.time, &args.session, &manifest)?; let window = timecode::parse_span(&args.window)?; let (from, to) = (center - window, center + window); @@ -219,8 +279,8 @@ pub(super) fn at(args: &AtArgs) -> eyre::Result<()> { pub(super) fn range(args: &RangeArgs) -> eyre::Result<()> { let (session, manifest) = load(&args.session)?; - let from = timecode::parse(&args.from)?; - let to = timecode::parse(&args.to)?; + let from = time_arg(&args.from, &args.session, &manifest)?; + let to = time_arg(&args.to, &args.session, &manifest)?; if to < from { eyre::bail!( "the range end {} is before its start {}", @@ -272,11 +332,26 @@ pub(super) fn summary(args: &SummaryArgs) -> eyre::Result<()> { pub(super) fn locate(args: &LocateArgs) -> eyre::Result<()> { let (session, manifest) = load(&args.session)?; let locator = if let Some(utc) = &args.utc { - let time: DateTime = DateTime::parse_from_rfc3339(utc) - .wrap_err_with(|| { - format!("'{utc}' is not an RFC 3339 time like 2026-10-26T19:43:35.062613Z") + let time: DateTime = if utc.starts_with("logtime:") || utc.starts_with("log-time:") { + // a time of day from the log: on the session's date, through the master clock + let moment = time_arg(utc, &args.session, &manifest)?; + let wall_us = crate::clock::ClockMap::new(manifest.anchors.clone()) + .mach_to_wall(manifest.mach_at_video_seconds(moment)) + .ok_or_else(|| { + crate::analysis::envelope::unusable("the session has no clock anchors") + })?; + DateTime::from_timestamp_micros(wall_us).ok_or_else(|| { + crate::analysis::envelope::unusable(format!("{wall_us} is not a time")) })? - .with_timezone(&Utc); + } else { + DateTime::parse_from_rfc3339(utc) + .wrap_err_with(|| { + format!( + "'{utc}' is not an RFC 3339 time like 2026-10-26T19:43:35.062613Z, or a log time like logtime:15:46:22.743" + ) + })? + .with_timezone(&Utc) + }; Locator::Utc(time) } else if let Some(line) = args.log_line { Locator::LogLine(line) @@ -300,7 +375,7 @@ pub(super) fn frames_command(args: &FramesArgs) -> eyre::Result<()> { let times = args .times .iter() - .map(|time| timecode::parse(time)) + .map(|time| time_arg(time, &args.session, &manifest)) .collect::>>()?; let extraction = frames::extract(&session, &manifest, ×, args.display)?; diff --git a/komorebi-recorder/src/guide.md b/komorebi-recorder/src/guide.md index 84b4b371..7e48e4a2 100644 --- a/komorebi-recorder/src/guide.md +++ b/komorebi-recorder/src/guide.md @@ -65,6 +65,18 @@ locations as hints. it was received. - komorebi logs no handler *end* line for events at INFO, and cannot show time spent waiting for the lock or in accessibility calls before the handler's header. `handler_ms` is a lower bound. +- A receive time is also when the recorder *got* the notification, which can be well after komorebi + sent it: notifications are sometimes delivered in clumps. komorebi's own send time is its DEBUG log + line `pushed notification to subscriber:`; where the log has it, an event's handler gives + `pushed_video_s` and `delivery_ms` beside the received `video_s`, and `handler_ms` ends at the + push. A large `delivery_ms`, or a `delivery-batching` finding, means delay between komorebi and + the recorder, not komorebi being slow: go by the pushed time. A `slow-handler` finding without a + push time may be the same thing, and says so. +- Every command that takes a time takes the same forms: video time (`12.5`, `1:02.5`, `1:02:03`), + `logtime:15:46:22.743` (a UTC time of day as komorebi's log writes it, on the session's date; + `wall:15:46:22.743` is the same), `wall:`, `mach:`, `event:N`, `log:N`, `incident:N`, + `bug:`, each with an offset like `+3s`. A bare `15:46:22` is video time, never a log time: + the prefix is what makes it one. - The state in a notification is the state *after* the event, plus anything background threads did since the last one. States can be stale: `age_ms` in `origin` says how long. - An `AXError` in komorebi's log comes from the application or the OS, not from komorebi. diff --git a/komorebi-recorder/src/report.rs b/komorebi-recorder/src/report.rs index be58b371..bb418dac 100644 --- a/komorebi-recorder/src/report.rs +++ b/komorebi-recorder/src/report.rs @@ -785,7 +785,7 @@ pub fn events_text(data: &EventsData, verbose: bool) -> String { } else { String::new() }; - format!(" handler{ms}{problems}") + format!(" handler{ms}{problems}{}", pushed_text(handler)) }); let state = match event.state_changed { Some(true) => " state changed", @@ -1003,22 +1003,31 @@ pub fn trace_text(data: &TraceData) -> String { event.reason ); if let Some(handler) = &event.handler { + let problems = if handler.errors + handler.warnings > 0 { + format!( + ", {} error(s), {} warning(s)", + handler.errors, handler.warnings + ) + } else { + String::new() + }; + let tail = format!("{}{problems}", pushed_text(handler)); let _ = writeln!( out, " handler logged {} line(s) from {}, began {}{}", handler.lines, timecode::format(handler.started_video_s), - handler.handler_ms.map_or_else(String::new, |ms| format!( - "{ms:.0} ms before it was received" - )), - if handler.errors + handler.warnings > 0 { - format!( - ", {} error(s), {} warning(s)", - handler.errors, handler.warnings - ) - } else { - String::new() - } + handler.handler_ms.map_or_else(String::new, |ms| { + if handler + .delivery_ms + .is_some_and(|delivery| delivery >= DELIVERY_NOTE_MS) + { + format!("{ms:.0} ms before komorebi sent the notification") + } else { + format!("{ms:.0} ms before it was received") + } + }), + tail ); } @@ -1236,6 +1245,22 @@ pub fn history_text(data: &HistoryData) -> String { out } +/// How long a notification must have been in transit for the text to say when komorebi sent it. +const DELIVERY_NOTE_MS: f64 = 100.0; + +/// ` pushed 00:01.850`: when komorebi sent the notification, if it was well before it was received. +fn pushed_text(handler: &crate::analysis::views::HandlerView) -> String { + match (handler.pushed_video_s, handler.delivery_ms) { + (Some(pushed), Some(delivery)) if delivery >= DELIVERY_NOTE_MS => { + format!( + " pushed {} ({delivery:.0} ms before received)", + timecode::format(pushed) + ) + } + _ => String::new(), + } +} + fn event_line(event: &EventView) -> String { let handler = event.handler.as_ref().map_or_else(String::new, |handler| { let ms = handler diff --git a/komorebi-recorder/src/testkit.rs b/komorebi-recorder/src/testkit.rs index 043dbbe6..ad9c9199 100644 --- a/komorebi-recorder/src/testkit.rs +++ b/komorebi-recorder/src/testkit.rs @@ -70,6 +70,7 @@ pub struct SessionBuilder { os_records: Vec, flavor: crate::analysis::flavor::Flavor, komorebi_commit: Option, + subscriber: Option, videos: Vec, } @@ -92,6 +93,7 @@ impl SessionBuilder { os_records: Vec::new(), flavor: crate::analysis::flavor::Flavor::Macos, komorebi_commit: None, + subscriber: None, videos: Vec::new(), } } @@ -138,6 +140,14 @@ impl SessionBuilder { self } + /// Say the recorder subscribed to komorebi under this name, as the manifest of a real session + /// does. It is what a `pushed notification to subscriber:` line in the log is matched to. + #[must_use] + pub fn subscriber(mut self, name: &str) -> Self { + self.subscriber = Some(name.to_string()); + self + } + /// Say the recording lasted this many seconds of video time. #[must_use] pub fn length(mut self, seconds: f64) -> Self { @@ -236,6 +246,7 @@ impl SessionBuilder { ], ); manifest.stop = Some(stop); + manifest.komorebi.subscriber.clone_from(&self.subscriber); manifest.komorebi.flavor = self.flavor; manifest.status = crate::session::STATUS_COMPLETE.to_string(); manifest.video_t0_mach_ns = Some(T0_MACH_NS); diff --git a/komorebi-recorder/tests/one_clock.rs b/komorebi-recorder/tests/one_clock.rs new file mode 100644 index 00000000..3960516d --- /dev/null +++ b/komorebi-recorder/tests/one_clock.rs @@ -0,0 +1,234 @@ +//! One clock for every time argument, and delivery delay that is not a slow handler, through the +//! real binary. +//! +//! Testkit time: video `t = 0` is 12:00:05 UTC, so video 2.0 s is 12:00:07. + +use komorebi_recorder::testkit::SessionBuilder; +use serde_json::Value; +use serde_json::json; +use std::process::Command; + +fn run(args: &[&str]) -> std::process::Output { + Command::new(env!("CARGO_BIN_EXE_komorebi-recorder")) + .args(args) + .output() + .expect("run komorebi-recorder") +} + +fn json(args: &[&str]) -> Value { + let output = run(args); + assert!( + output.status.success(), + "{args:?} failed: {}", + String::from_utf8_lossy(&output.stderr) + ); + serde_json::from_slice(&output.stdout).expect("JSON") +} + +fn move_end(pid: i64) -> Value { + json!({"type": "MoveEnd", "content": [{"type": "Accessibility", "content": "AXWindowMoved"}, pid, 7]}) +} + +fn focus(pid: i64) -> Value { + json!({"type": "FocusChange", "content": [{"type": "Accessibility", "content": "AXApplicationActivated"}, pid, 7]}) +} + +const MOVE_HEADER: &str = "process_event: komorebi::process_event: processing event: MoveEnd for process 10 with notification AXWindowMoved"; +const FOCUS_HEADER: &str = "process_event: komorebi::process_event: processing event: FocusChange for process 11 with notification AXApplicationActivated"; +const PUSH: &str = + "process_event: komorebi::notify: pushed notification to subscriber: komorebi-recorder-7"; + +#[test] +fn at_takes_a_log_time_and_a_video_time_to_the_same_place() { + let (session, _) = SessionBuilder::new("one-clock-at") + .event(3.0, move_end(10), None) + .log(2.0, "INFO", MOVE_HEADER) + .build(); + let dir = session.dir.display().to_string(); + + // 12:00:07 UTC is 2 s into the video + for time in [ + "2.0", + "logtime:12:00:07", + "log-time:12:00:07.000", + "wall:12:00:07", + "wall:2026-10-26T12:00:07Z", + ] { + let answer = json(&["at", &dir, time, "--window", "100ms", "--json"]); + let center = answer["center_s"].as_f64().expect("center"); + assert!((center - 2.0).abs() < 1e-3, "{time}: {center}"); + } + + // offsets work, on a log time as on a video time + let answer = json(&[ + "at", + &dir, + "logtime:12:00:07+1s", + "--window", + "100ms", + "--json", + ]); + assert!((answer["center_s"].as_f64().expect("center") - 3.0).abs() < 1e-3); + let answer = json(&["at", &dir, "1.0+1s", "--window", "100ms", "--json"]); + assert!((answer["center_s"].as_f64().expect("center") - 2.0).abs() < 1e-3); + + // the log time finds the log line, which is at video 2.0 + let answer = json(&[ + "at", + &dir, + "logtime:12:00:07", + "--window", + "100ms", + "--json", + ]); + assert!(answer["count"].as_u64().expect("count") >= 1, "{answer}"); + + // a bare time of day is video time, as it always was + let answer = json(&["at", &dir, "0:02.5", "--window", "100ms", "--json"]); + assert!((answer["center_s"].as_f64().expect("center") - 2.5).abs() < 1e-3); + + // an event is a time too + let answer = json(&["at", &dir, "event:1.end", "--window", "100ms", "--json"]); + assert!((answer["center_s"].as_f64().expect("center") - 3.0).abs() < 0.05); +} + +#[test] +fn range_and_locate_take_a_log_time() { + let (session, _) = SessionBuilder::new("one-clock-range") + .event(3.0, move_end(10), None) + .build(); + let dir = session.dir.display().to_string(); + + let answer = json(&[ + "range", + &dir, + "logtime:12:00:06", + "logtime:12:00:08", + "--json", + ]); + assert!((answer["from_s"].as_f64().expect("from") - 1.0).abs() < 1e-3); + assert!((answer["to_s"].as_f64().expect("to") - 3.0).abs() < 1e-3); + + let located = json(&["locate", &dir, "--utc", "logtime:12:00:07.500", "--json"]); + assert!( + (located["video_s"].as_f64().expect("video") - 2.5).abs() < 1e-3, + "{located}" + ); + + let output = run(&["at", &dir, "logtime:noon", "--json"]); + assert!(!output.status.success()); + assert!(String::from_utf8_lossy(&output.stderr).contains("logtime:15:46:22.743")); +} + +/// Four notifications komorebi sent half a second apart, all received within 3 ms at 5 s. +fn batched(name: &str, subscriber: bool) -> String { + let mut builder = SessionBuilder::new(name) + .event(5.000, move_end(10), None) + .event(5.001, focus(11), None) + .event(5.002, move_end(10), None) + .event(5.003, focus(11), None) + .log(2.0, "INFO", MOVE_HEADER) + .log(2.005, "DEBUG", PUSH) + .log(2.5, "INFO", FOCUS_HEADER) + .log(2.505, "DEBUG", PUSH) + .log(3.0, "INFO", MOVE_HEADER) + .log(3.005, "DEBUG", PUSH) + .log(3.5, "INFO", FOCUS_HEADER) + .log(3.505, "DEBUG", PUSH); + if subscriber { + builder = builder.subscriber("komorebi-recorder-7"); + } + let (session, _) = builder.build(); + session.dir.display().to_string() +} + +fn findings(dir: &str) -> Vec { + json(&["overview", dir, "--json"])["data"]["findings"] + .as_array() + .expect("findings") + .clone() +} + +#[test] +fn notifications_received_in_a_clump_are_delivery_batching_not_slow_handlers() { + let dir = batched("one-clock-batched", true); + let found = findings(&dir); + + let batching = found + .iter() + .find(|finding| finding["kind"] == "delivery-batching") + .unwrap_or_else(|| panic!("no delivery-batching in {found:#?}")); + assert_eq!(batching["severity"], "info"); + let summary = batching["summary"].as_str().expect("summary"); + assert!(summary.contains("4 events"), "{summary}"); + assert!(summary.contains("delivery delay"), "{summary}"); + + // komorebi handled each in 5 ms: nothing was slow + assert!( + found + .iter() + .all(|finding| finding["kind"] != "slow-handler"), + "{found:#?}" + ); + + // the events say when komorebi sent them, beside when they were received + let events = json(&["events", &dir, "--json"]); + let first = &events["data"]["events"][0]; + assert!((first["video_s"].as_f64().expect("received") - 5.0).abs() < 1e-3); + assert!( + (first["handler"]["pushed_video_s"].as_f64().expect("pushed") - 2.005).abs() < 1e-3, + "{first}" + ); + assert!((first["handler"]["delivery_ms"].as_f64().expect("delivery") - 2995.0).abs() < 1.0); + assert!((first["handler"]["handler_ms"].as_f64().expect("handler") - 5.0).abs() < 1.0); + + // and a trace of one says it was delivery delay + let trace = String::from_utf8_lossy(&run(&["trace", &dir, "event:2"]).stdout).into_owned(); + assert!(trace.contains("delivery delay"), "{trace}"); +} + +#[test] +fn without_komorebis_push_time_a_slow_handler_may_be_delivery_delay() { + let dir = batched("one-clock-unpushed", false); + let found = findings(&dir); + + let slow = found + .iter() + .find(|finding| finding["kind"] == "slow-handler") + .unwrap_or_else(|| panic!("no slow-handler in {found:#?}")); + // 3 s is long enough to have been a warning when the numbers were trusted + assert_eq!(slow["severity"], "info"); + assert!( + slow["summary"] + .as_str() + .expect("summary") + .contains("may be delivery delay"), + "{slow}" + ); + // without push lines only the one event with a header to go by is paired, so there is no + // batch to describe +} + +#[test] +fn a_handler_that_really_was_slow_is_still_a_slow_handler() { + // received 1.5 s after the handler began, and the push says komorebi sent it just then + let (session, _) = SessionBuilder::new("one-clock-slow") + .event(3.5, move_end(10), None) + .log(2.0, "INFO", MOVE_HEADER) + .log(3.49, "DEBUG", PUSH) + .subscriber("komorebi-recorder-7") + .build(); + let dir = session.dir.display().to_string(); + + let found = findings(&dir); + let slow = found + .iter() + .find(|finding| finding["kind"] == "slow-handler") + .unwrap_or_else(|| panic!("no slow-handler in {found:#?}")); + assert_eq!(slow["severity"], "warn"); + assert!( + found + .iter() + .all(|finding| finding["kind"] != "delivery-batching") + ); +}