diff --git a/Cargo.lock b/Cargo.lock index 87c905ce..0fb5ee19 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -233,6 +233,15 @@ version = "0.8.7" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" +[[package]] +name = "crc32fast" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511" +dependencies = [ + "cfg-if", +] + [[package]] name = "crossbeam-channel" version = "0.5.15" @@ -319,12 +328,31 @@ version = "2.4.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6" +[[package]] +name = "fdeflate" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c" +dependencies = [ + "simd-adler32", +] + [[package]] name = "find-msvc-tools" version = "0.1.9" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582" +[[package]] +name = "flate2" +version = "1.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c" +dependencies = [ + "crc32fast", + "miniz_oxide", +] + [[package]] name = "foldhash" version = "0.1.5" @@ -498,6 +526,7 @@ dependencies = [ "objc2-foundation", "objc2-screen-capture-kit", "parking_lot", + "png", "schemars", "serde", "serde_json_lenient", @@ -575,6 +604,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316" dependencies = [ "adler2", + "simd-adler32", ] [[package]] @@ -789,6 +819,19 @@ version = "0.2.17" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" +[[package]] +name = "png" +version = "0.18.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61" +dependencies = [ + "bitflags", + "crc32fast", + "fdeflate", + "flate2", + "miniz_oxide", +] + [[package]] name = "prettyplease" version = "0.2.37" @@ -1012,6 +1055,12 @@ version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" +[[package]] +name = "simd-adler32" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "703d5c7ef118737c72f1af64ad2f6f8c5e1921f818cdcb97b8fe6fc69bf66214" + [[package]] name = "slab" version = "0.4.12" diff --git a/dependencies.json b/dependencies.json index 192f8b6c..b8efaa19 100644 --- a/dependencies.json +++ b/dependencies.json @@ -29,6 +29,7 @@ "color-spantrace 0.3.0 registry+https://github.com/rust-lang/crates.io-index", "colorchoice 1.0.5 registry+https://github.com/rust-lang/crates.io-index", "core-foundation-sys 0.8.7 registry+https://github.com/rust-lang/crates.io-index", + "crc32fast 1.5.0 registry+https://github.com/rust-lang/crates.io-index", "crossbeam-channel 0.5.15 registry+https://github.com/rust-lang/crates.io-index", "crossbeam-utils 0.8.21 registry+https://github.com/rust-lang/crates.io-index", "dirs 6.0.0 registry+https://github.com/rust-lang/crates.io-index", @@ -38,6 +39,8 @@ "errno 0.3.14 registry+https://github.com/rust-lang/crates.io-index", "eyre 0.6.12 registry+https://github.com/rust-lang/crates.io-index", "fastrand 2.4.1 registry+https://github.com/rust-lang/crates.io-index", + "fdeflate 0.3.7 registry+https://github.com/rust-lang/crates.io-index", + "flate2 1.1.9 registry+https://github.com/rust-lang/crates.io-index", "getrandom 0.4.2 registry+https://github.com/rust-lang/crates.io-index", "gimli 0.32.3 registry+https://github.com/rust-lang/crates.io-index", "heck 0.5.0 registry+https://github.com/rust-lang/crates.io-index", @@ -62,6 +65,7 @@ "parking_lot 0.12.5 registry+https://github.com/rust-lang/crates.io-index", "parking_lot_core 0.9.12 registry+https://github.com/rust-lang/crates.io-index", "pin-project-lite 0.2.17 registry+https://github.com/rust-lang/crates.io-index", + "png 0.18.1 registry+https://github.com/rust-lang/crates.io-index", "proc-macro2 1.0.106 registry+https://github.com/rust-lang/crates.io-index", "quote 1.0.45 registry+https://github.com/rust-lang/crates.io-index", "ref-cast 1.0.25 registry+https://github.com/rust-lang/crates.io-index", @@ -145,6 +149,7 @@ "color-spantrace 0.3.0 registry+https://github.com/rust-lang/crates.io-index", "colorchoice 1.0.5 registry+https://github.com/rust-lang/crates.io-index", "core-foundation-sys 0.8.7 registry+https://github.com/rust-lang/crates.io-index", + "crc32fast 1.5.0 registry+https://github.com/rust-lang/crates.io-index", "crossbeam-channel 0.5.15 registry+https://github.com/rust-lang/crates.io-index", "crossbeam-utils 0.8.21 registry+https://github.com/rust-lang/crates.io-index", "dirs 6.0.0 registry+https://github.com/rust-lang/crates.io-index", @@ -154,6 +159,8 @@ "errno 0.3.14 registry+https://github.com/rust-lang/crates.io-index", "eyre 0.6.12 registry+https://github.com/rust-lang/crates.io-index", "fastrand 2.4.1 registry+https://github.com/rust-lang/crates.io-index", + "fdeflate 0.3.7 registry+https://github.com/rust-lang/crates.io-index", + "flate2 1.1.9 registry+https://github.com/rust-lang/crates.io-index", "getrandom 0.4.2 registry+https://github.com/rust-lang/crates.io-index", "gimli 0.32.3 registry+https://github.com/rust-lang/crates.io-index", "heck 0.5.0 registry+https://github.com/rust-lang/crates.io-index", @@ -184,6 +191,7 @@ "parking_lot 0.12.5 registry+https://github.com/rust-lang/crates.io-index", "parking_lot_core 0.9.12 registry+https://github.com/rust-lang/crates.io-index", "pin-project-lite 0.2.17 registry+https://github.com/rust-lang/crates.io-index", + "png 0.18.1 registry+https://github.com/rust-lang/crates.io-index", "proc-macro2 1.0.106 registry+https://github.com/rust-lang/crates.io-index", "quote 1.0.45 registry+https://github.com/rust-lang/crates.io-index", "ref-cast 1.0.25 registry+https://github.com/rust-lang/crates.io-index", @@ -200,6 +208,7 @@ "serde_json 1.0.149 registry+https://github.com/rust-lang/crates.io-index", "serde_json_lenient 0.2.4 registry+https://github.com/rust-lang/crates.io-index", "sharded-slab 0.1.7 registry+https://github.com/rust-lang/crates.io-index", + "simd-adler32 0.3.9 registry+https://github.com/rust-lang/crates.io-index", "smallvec 1.15.1 registry+https://github.com/rust-lang/crates.io-index", "strsim 0.11.1 registry+https://github.com/rust-lang/crates.io-index", "syn 2.0.117 registry+https://github.com/rust-lang/crates.io-index", diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 33316dae..9e6db737 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -77,6 +77,9 @@ only when they changed), and what happened to the recording itself (`recorder.js The OS trace is under `oslog/`, one file per stream. Each display's video is `video-[-].mp4` with a `frames-[-].csv` beside it holding every frame's timestamp, one segment to a file: a display that is unplugged and returns starts a new segment instead of extending the old one. +`timeline.jsonl` is the only derived file: a time-sorted index of every record that points into the raw files by byte +range. Anything that happens to the recorder leaves the raw files readable, and the index is rebuilt from them with +`reindex`. The file formats are specified on the `session` and `timeline` modules. ## Recording @@ -101,3 +104,4 @@ backend that docks and undocks without hardware. | A running recorder can be told from one that died | the OS: an exclusive lock on `recorder.lock`, held for as long as the recorder runs and dropped by the OS when the process ends however it ends | | A manifest from a newer build is not read | a runtime error when the manifest is read, covered by `rejects_manifests_from_the_future` | | A manifest is never half-written | write to a temporary file and rename | +| The raw files are never rewritten | convention: the index only references them, and `reindex` rebuilds the index from them | diff --git a/komorebi-recorder/Cargo.toml b/komorebi-recorder/Cargo.toml index 2b8c6bbc..8a8d8ada 100644 --- a/komorebi-recorder/Cargo.toml +++ b/komorebi-recorder/Cargo.toml @@ -12,6 +12,7 @@ color-eyre = { workspace = true } crossbeam-channel = { workspace = true } dirs = { workspace = true } parking_lot = { workspace = true } +png = "0.18" schemars = { workspace = true } serde = { workspace = true } serde_json = { workspace = true } diff --git a/komorebi-recorder/src/frames.rs b/komorebi-recorder/src/frames.rs new file mode 100644 index 00000000..aef4988f --- /dev/null +++ b/komorebi-recorder/src/frames.rs @@ -0,0 +1,273 @@ +//! Extracting still frames from a session's video so the exact moment can be looked at. +//! +//! `ffmpeg` is used to extract stills, here, and by the self-test to read its clock strip; it is +//! never used for capture or for playback. Frames in the mp4 only exist where the screen +//! changed, so the frame returned for a timecode is the most recent one at or before it - which +//! is exactly what was on screen at that moment. +//! +//! This is the `frames` command: [`extract`] picks, for each time asked for, the segment of each +//! display that has video then (see [`crate::session::Manifest::segment_at`]), seeks to the right +//! place in that segment's file, and writes a PNG into the session's `frames/` directory. A display +//! with no video at that moment (unplugged, asleep, between segments) is reported, not an error. +//! +//! Nothing here is specific to a host or a komorebi flavor: the video is an mp4 either way, and +//! `ffmpeg` reads it. What differs by OS is only how to get `ffmpeg` ([`ffmpeg_install_hint`]). + +use crate::session::Manifest; +use crate::session::Session; +use crate::timecode; +use color_eyre::eyre; +use color_eyre::eyre::WrapErr; +use serde::Serialize; +use std::path::PathBuf; +use std::process::Command; + +/// A still frame that [`extract`] wrote. +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct ExtractedFrame { + /// The id of the display the frame is of. + pub display: u32, + /// The time that was asked for, in seconds of video time. + pub video_s: f64, + /// The time within the display's own file. + pub file_s: f64, + /// Where the PNG was written: [`frame_path`] of the display and `video_s`. + pub path: PathBuf, +} + +/// Returns where the frame for `video_s` on `display` goes: `frames/frame--t.png` +/// in the session directory. +/// +/// The time is written in seconds with three decimals, zero padded to nine characters, so the +/// names of one display's frames sort in time order for any time below 100,000 seconds. The time +/// is the one asked for, not the time of the frame ffmpeg found. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::frames::frame_path; +/// use komorebi_recorder::session::Session; +/// use std::path::PathBuf; +/// +/// let session = Session { dir: PathBuf::from("/s") }; +/// let earlier = frame_path(&session, 2, 9.5); +/// let later = frame_path(&session, 2, 12.25); +/// assert_eq!(later, PathBuf::from("/s/frames/frame-2-t00012.250.png")); +/// assert!(earlier < later); +/// ``` +#[must_use] +pub fn frame_path(session: &Session, display: u32, video_s: f64) -> PathBuf { + session.path(format!("frames/frame-{display}-t{video_s:09.3}.png")) +} + +/// Returns how to get `ffmpeg` on this OS, as a fragment to put in a sentence: `winget` or `scoop` +/// on Windows, `brew` or the `nix develop` shell on macOS, and the package manager elsewhere. +#[must_use] +pub fn ffmpeg_install_hint() -> &'static str { + if cfg!(windows) { + "e.g. `winget install Gyan.FFmpeg` or `scoop install ffmpeg`" + } else if cfg!(target_os = "macos") { + "e.g. `brew install ffmpeg`, or use `nix develop`, which provides it" + } else { + "with your package manager" + } +} + +/// Returns true if and only if `ffmpeg` can be run: `ffmpeg -version` is found on `PATH` and +/// succeeds. +#[must_use] +pub fn ffmpeg_available() -> bool { + Command::new("ffmpeg") + .arg("-version") + .output() + .is_ok_and(|output| output.status.success()) +} + +/// A display that was asked for but had no video at the requested moment. +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct Skipped { + /// The id of the display. + pub display: u32, + /// The time that was asked for, in seconds of video time. + pub video_s: f64, + /// Why there was no video, as a sentence. + pub reason: String, +} + +/// What [`extract`] produced: the frames it wrote and the displays it had to leave out. +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct Extraction { + /// The frames written, in the order of the times asked for and, within a time, of the displays' + /// ids. + pub frames: Vec, + /// The displays that had no video at a time asked for. A time at which every display was + /// skipped is an error, so each time asked for has at least one frame in `frames`. + pub skipped: Vec, +} + +/// Extracts a frame at each of `times` from every display (or just `display`) that has video then. +/// +/// A display that was unplugged, asleep or between segments at that moment is reported in +/// `skipped` rather than failing the others. +/// +/// `times` are in seconds of video time (see [`crate::timecode`]). For each, and each display +/// wanted, the segment with video at that time is found with +/// [`Manifest::segment_at`](crate::session::Manifest::segment_at), which allows 50 ms either side +/// of a segment's span. `ffmpeg` is asked for one frame at that time in the segment's file +/// (`file_s`, never below zero), and writes it to [`frame_path`]. Because the video has frames only +/// where the screen changed, that frame is the latest one at or before the time. An existing frame +/// at the same path is overwritten. +/// +/// `display` limits the extraction to one display id; `None` is every display recorded. +/// +/// # Errors +/// +/// Returns an error if +/// +/// * `ffmpeg` cannot be run (the message says how to install it for this OS); +/// * the session has no recorded video, or none for `display`; +/// * a time is before the first frame or more than half a second after the end of the recorded +/// video (the message gives the span); +/// * no display has video at a time (the message names the displays); +/// * the `frames/` directory cannot be created, or `ffmpeg` fails or writes no file (the message +/// has what `ffmpeg` said). +/// +/// Frames already written for earlier times stay on disk when a later time fails. +/// +/// # Example +/// +/// ```rust,no_run +/// use komorebi_recorder::frames::extract; +/// use komorebi_recorder::session::Session; +/// +/// let session = Session::open("/path/to/recordings/20261026T120000Z")?; +/// let manifest = session.manifest()?; +/// +/// // what was on screen at 12.5 s and at 14 s, on every display that had video then +/// let extraction = extract(&session, &manifest, &[12.5, 14.0], None)?; +/// for frame in &extraction.frames { +/// println!("display {} at {:.3} s into its file: {}", frame.display, frame.file_s, frame.path.display()); +/// } +/// # Ok::<(), Box>(()) +/// ``` +/// +/// This needs `ffmpeg` and a recorded session, so it is not run, and no test covers it: the +/// `frames` command is the check. What it can be checked against without video is the file name +/// ([`frame_path`], and the test `frame_paths_sort_chronologically`) and the segment lookup +/// (`Manifest::segment_at`, in the tests of `timeline`). +pub fn extract( + session: &Session, + manifest: &Manifest, + times: &[f64], + display: Option, +) -> eyre::Result { + if !ffmpeg_available() { + eyre::bail!( + "ffmpeg was not found on PATH; install it ({}) to extract frames", + ffmpeg_install_hint() + ); + } + + let ids: Vec = manifest + .display_ids() + .into_iter() + .filter(|id| display.is_none_or(|wanted| wanted == *id)) + .collect(); + + if ids.is_empty() { + eyre::bail!(match display { + Some(id) => format!("display {id} has no recorded video in this session"), + None => "this session has no recorded video".to_string(), + }); + } + + std::fs::create_dir_all(session.path("frames"))?; + let (_, duration) = manifest.video_span(); + let mut extraction = Extraction { + frames: Vec::new(), + skipped: Vec::new(), + }; + + for &video_s in times { + if video_s < 0.0 || video_s > duration + 0.5 { + eyre::bail!( + "{} is outside the recorded video (00:00.000 to {})", + timecode::format(video_s), + timecode::format(duration) + ); + } + + let before = extraction.frames.len(); + for &id in &ids { + let Some(entry) = manifest.segment_at(id, video_s) else { + extraction.skipped.push(Skipped { + display: id, + video_s, + reason: "no video for this display at that moment (it was unplugged, asleep, \ + or its stream had stopped)" + .to_string(), + }); + continue; + }; + + let file_s = (video_s - entry.offset_s).max(0.0); + let path = frame_path(session, id, video_s); + let output = Command::new("ffmpeg") + .args(["-y", "-v", "error", "-ss", &format!("{file_s:.3}"), "-i"]) + .arg(session.path(&entry.result.file)) + .args(["-frames:v", "1"]) + .arg(&path) + .output() + .wrap_err("could not run ffmpeg")?; + + if !output.status.success() || !path.is_file() { + eyre::bail!( + "ffmpeg could not extract a frame at {} from {}: {}", + timecode::format(file_s), + entry.result.file, + String::from_utf8_lossy(&output.stderr).trim() + ); + } + + extraction.frames.push(ExtractedFrame { + display: id, + video_s, + file_s, + path, + }); + } + + if extraction.frames.len() == before { + eyre::bail!( + "no display has video at {}: {}", + timecode::format(video_s), + extraction + .skipped + .iter() + .filter(|skipped| skipped.video_s == video_s) + .map(|skipped| format!("display {}", skipped.display)) + .collect::>() + .join(", ") + ); + } + } + + Ok(extraction) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn frame_paths_sort_chronologically() { + let session = Session { + dir: PathBuf::from("/s"), + }; + let a = frame_path(&session, 2, 9.5); + let b = frame_path(&session, 2, 12.25); + assert_eq!(a, PathBuf::from("/s/frames/frame-2-t00009.500.png")); + assert_eq!(b, PathBuf::from("/s/frames/frame-2-t00012.250.png")); + assert!(a < b); + } +} diff --git a/komorebi-recorder/src/lib.rs b/komorebi-recorder/src/lib.rs index 010c2a38..046fa955 100644 --- a/komorebi-recorder/src/lib.rs +++ b/komorebi-recorder/src/lib.rs @@ -50,6 +50,7 @@ //! | [`session`] | the session directory and its manifest | //! | [`capture`] | capturing the screen into segments of video | //! | [`power`] and [`system_state`] | sleep, wake, lock and display changes | +//! | [`timeline`] and [`frames`] | the time-sorted index of a session and the frame times of its video | //! //! # What is not supported //! @@ -65,6 +66,7 @@ pub mod analysis; pub mod capture; pub mod clock; +pub mod frames; pub mod incidents; pub mod komorebi_link; pub mod lock; @@ -74,3 +76,4 @@ pub mod session; pub mod sources; pub mod system_state; pub mod timecode; +pub mod timeline; diff --git a/komorebi-recorder/src/timeline.rs b/komorebi-recorder/src/timeline.rs new file mode 100644 index 00000000..82776086 --- /dev/null +++ b/komorebi-recorder/src/timeline.rs @@ -0,0 +1,2008 @@ +//! The merged, sorted index over every raw file in a session, and the queries on top of it. +//! +//! `timeline.jsonl` holds one line per record: its time on every clock plus a *reference* +//! (`file`, `offset`, `len`) into a raw file. Raw data is never copied or rewritten, so the index +//! can be rebuilt at any time (`reindex`) and the streams stay separate. +//! +//! Queries binary-search the sorted file by byte offset, so asking about one second of a +//! multi-gigabyte session does not load the index into memory. +//! +//! # The pieces +//! +//! | Item | Does | +//! |---|---| +//! | [`build`] | reads the raw files and the manifest, and writes `timeline.jsonl` | +//! | [`query`] | the records whose time is in a range of video time, optionally narrowed by a [`Filter`] | +//! | [`summary`] | a per-bucket digest of the whole recording ([`Bucket`]) | +//! | [`locate`] | the reverse: a [`Locator`] (a UTC time, a log line, an event) to its video time ([`Located`]) | +//! | [`render`], [`strip_ansi`], [`format_wall_us`] | pure formatting of a record, of text, and of a time | +//! +//! This module reads a session and is the same on every host and for either komorebi flavor. The +//! host that recorded it shows only in what is in the raw files (the OS trace of a Mac, or of +//! Windows) and in the tick size of the manifest's timebase. Which komorebi produced the log and +//! events is not looked at here: it is a matter for `analysis`. +//! +//! # The file: `timeline.jsonl` +//! +//! The index is UTF-8, one JSON object per line ([`TimelineEntry`]), each line ending in `\n`, and +//! is sorted by `mach_ns`, ascending. Records with the same `mach_ns` are ordered by the order in +//! which their source was first met while building (`komorebi-log`, `events`, `recorder`, then the +//! OS trace files in order of path), then by file, then by `offset`. [`build`] writes it to +//! `timeline.jsonl.tmp` and renames that over `timeline.jsonl`, so a reader never sees a +//! half-written index. +//! +//! | Field | JSON | Is | +//! |---|---|---| +//! | `video_s` | number | the record's time in video time: seconds since the first captured frame, negative before it. It is the manifest's `video_seconds` of `mach_ns` as the manifest was when the index was built | +//! | `mach_ns` | integer | the record's time on the master clock, in nanoseconds (see [`crate::clock`]) | +//! | `wall_utc` | string or `null` | the same time as RFC 3339 UTC with microseconds, `2027-01-15T08:00:02.000000Z`, worked out from the manifest's anchors. `null` if that cannot be done, which is if the manifest has none | +//! | `source` | string | which stream the record is from, see below | +//! | `pid` | integer, left out if unknown | the process the record is about: an OS trace record's `processID`, or the process id a window manager event carries | +//! | `file` | string | the raw file, relative to the session directory, always with `/` separators | +//! | `offset` | integer | the byte offset in `file` of the start of the record | +//! | `len` | integer | how many bytes the record is, including its line terminator | +//! | `line` | integer | the record's 1-based line number in `file` | +//! | `seq` | integer, left out for all but events | the subscriber event sequence number | +//! +//! `file`, `offset` and `len` are the reference: the raw record is `len` bytes at `offset` of +//! `file`, with a trailing `\n` or `\r\n` removed when it is shown. Nothing but the reference +//! points into the raw files, so a raw file edited by hand needs a `reindex`, and an index older +//! than its raw files can point into the wrong bytes. +//! +//! # The sources +//! +//! | `source` | Raw file | Time of a record | +//! |---|---|---| +//! | `komorebi-log` ([`SOURCE_KOMOREBI_LOG`]) | `komorebi.log` | the line's UTC time, through the manifest's anchors ([`crate::clock::ClockMap`]) | +//! | `events` ([`SOURCE_EVENTS`]) | `events.jsonl` | `recv_mach_ns`, stamped on the master clock when the recorder received it | +//! | `recorder` ([`SOURCE_RECORDER`]) | `recorder.jsonl` | the incident's `mach_ns` (see [`crate::incidents`]) | +//! | `oslog:komorebi`, `oslog:system`, `oslog:eventlog`, `oslog:all`, `oslog:app:` | every `.ndjson` file in `oslog/` and `oslog/apps/` | `hostNs` if the line has one (the Windows OS trace), else its `machTimestamp` ticks converted with the manifest's timebase | +//! +//! The OS trace sources keep the `oslog:` prefix on every host, though on Windows it is not the +//! unified log. A file's source is the one the manifest lists for it; for a file it does not list, +//! such as one added by hand, it comes from the file's name: `komorebi.ndjson` and +//! `komorebi-.ndjson` are `oslog:komorebi`, `system.ndjson`, `eventlog.ndjson` and +//! `all.ndjson` are `oslog:system`, `oslog:eventlog` and `oslog:all`, and any other is +//! `oslog:app:`, with a trailing `-` taken off. +//! +//! A line is left out of the index if it has no time: a line of `komorebi.log` before the first +//! timestamped one, and every line of it if the manifest has no anchors; a row of `events.jsonl` +//! or `recorder.jsonl` that is not valid JSON of the right shape, such as one cut short by a crash; +//! an OS trace line with neither `hostNs` nor `machTimestamp`. Continuation lines of +//! `komorebi.log` (a panic message, a backtrace) are in the index, with the time of the line they +//! follow. +//! +//! # Cost +//! +//! [`build`] holds one compact record per index entry in memory while it sorts, and reads +//! `komorebi.log` whole. [`query`] does not load the index: it finds its starting place by binary +//! search on byte offsets, and reads only the lines in the range. [`summary`] reads the whole +//! index, one line at a time. [`locate`] does not use the index at all: it reads `komorebi.log` or +//! `events.jsonl`, and the manifest. +//! +//! # Example +//! +//! Building the index of a small session, and asking it questions: +//! +//! ```rust +//! use chrono::Utc; +//! use komorebi_recorder::clock::Anchor; +//! use komorebi_recorder::session::{Manifest, Moment, Session, TIMELINE_FILE}; +//! use komorebi_recorder::timeline::{self, Filter, Locator, TimelineEntry}; +//! +//! let dir = std::env::temp_dir().join(format!("komorebi-recorder-doc-timeline-{}", std::process::id())); +//! let _ = std::fs::remove_dir_all(&dir); +//! let session = Session::create(Some(dir.clone()), Utc::now())?; +//! +//! // the wall clock read 2027-01-15T08:00:00Z when the master clock read 100 s, which is also +//! // when the first video frame was captured: video time 0 is master clock time 100 s +//! let anchor = Anchor { wall_us: 1_800_000_000_000_000, mach_ns: 100_000_000_000 }; +//! let start = Moment { mach_ns: anchor.mach_ns, wall_us: anchor.wall_us }; +//! let mut manifest = Manifest::new(start, vec![anchor]); +//! manifest.video_t0_mach_ns = Some(anchor.mach_ns); +//! manifest.video_end_mach_ns = Some(110_000_000_000); +//! session.write_manifest(&manifest)?; +//! +//! // komorebi's log is stamped with the wall clock: this line is 2 s into the video +//! std::fs::write( +//! session.path("komorebi.log"), +//! "2027-01-15T08:00:02.000000Z INFO komorebi::process_event: processing event: Show\n", +//! )?; +//! // an event is stamped with the master clock when it is received, 10 ms later +//! std::fs::write( +//! session.path("events.jsonl"), +//! concat!( +//! r#"{"seq":1,"recv_wall_us":1800000002010000,"recv_mach_ns":102010000000,"#, +//! r#""event":{"type":"Show","content":[{"type":"Accessibility","content":"AXWindowCreated"},111,7]}}"#, +//! "\n", +//! ), +//! )?; +//! +//! let stats = timeline::build(&session)?; +//! assert_eq!(stats.entries, 2); +//! assert_eq!(stats.by_source["komorebi-log"], 1); +//! assert_eq!(stats.by_source["events"], 1); +//! +//! // the index: one entry per record, sorted by time, pointing into the raw files +//! let index = std::fs::read_to_string(session.path(TIMELINE_FILE))?; +//! let entries: Vec = index +//! .lines() +//! .map(serde_json::from_str) +//! .collect::>()?; +//! assert_eq!(entries[0].source, "komorebi-log"); +//! assert_eq!(entries[0].video_s, 2.0); +//! assert_eq!(entries[0].wall_utc.as_deref(), Some("2027-01-15T08:00:02.000000Z")); +//! assert_eq!((entries[0].file.as_str(), entries[0].offset, entries[0].line), ("komorebi.log", 0, 1)); +//! assert_eq!(entries[1].source, "events"); +//! assert_eq!(entries[1].pid, Some(111)); +//! assert_eq!(entries[1].seq, Some(1)); +//! +//! // what happened between 1.5 s and 2.5 s into the video? +//! let records = timeline::query(&session, &manifest, 1.5, 2.5, &Filter::default())?; +//! assert_eq!(records.len(), 2); +//! assert!(records[0].text.ends_with("processing event: Show")); +//! assert!(records[1].text.starts_with("#1 {")); +//! +//! // only the events +//! let only_events = Filter { sources: vec!["events".to_string()], ..Filter::default() }; +//! assert_eq!(timeline::query(&session, &manifest, 0.0, 10.0, &only_events)?.len(), 1); +//! +//! // and the reverse: where in the video is line 1 of komorebi's log? +//! let located = timeline::locate(&session, &manifest, &Locator::LogLine(1))?; +//! assert_eq!(located.video_s, 2.0); +//! assert!(located.in_video); +//! # std::fs::remove_dir_all(&dir)?; +//! # Ok::<(), Box>(()) +//! ``` + +use crate::clock::ClockMap; +use crate::incidents::INCIDENTS_FILE; +use crate::incidents::Incident; +use crate::session::Manifest; +use crate::session::Session; +use crate::session::TIMELINE_FILE; +use crate::sources::komorebi_events::EventRow; +use crate::sources::komorebi_log; +use crate::sources::managed_apps; +use crate::sources::oslog; +use crate::sources::oslog::OsLogRecord; +use chrono::DateTime; +use chrono::Utc; +use color_eyre::eyre; +use color_eyre::eyre::WrapErr; +use serde::Deserialize; +use serde::Serialize; +use std::collections::BTreeMap; +use std::collections::HashMap; +use std::fs::File; +use std::io::BufRead; +use std::io::BufReader; +use std::io::BufWriter; +use std::io::Read; +use std::io::Seek; +use std::io::SeekFrom; +use std::io::Write; + +/// The timeline source of komorebi's log: `komorebi-log`. +pub const SOURCE_KOMOREBI_LOG: &str = "komorebi-log"; +/// The timeline source of the subscriber's events: `events`. +pub const SOURCE_EVENTS: &str = "events"; +/// The timeline source of incidents: `recorder` (see [`crate::incidents`]). +pub use crate::incidents::SOURCE_RECORDER; + +/// One line of `timeline.jsonl`: a record's time on every clock, and where the record is. +/// +/// The fields are written in the order they are declared here. The format of the file, with what +/// each field means, is in the [module docs](self#the-file-timelinejsonl). +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::timeline::TimelineEntry; +/// +/// // `pid` and `seq` are left out when there is none, and `wall_utc` is `null` when unknown +/// let entry = TimelineEntry { +/// video_s: 2.5, +/// mach_ns: 102_500_000_000, +/// wall_utc: None, +/// source: "recorder".to_string(), +/// pid: None, +/// file: "recorder.jsonl".to_string(), +/// offset: 120, +/// len: 98, +/// line: 2, +/// seq: None, +/// }; +/// assert_eq!( +/// serde_json::to_string(&entry)?, +/// r#"{"video_s":2.5,"mach_ns":102500000000,"wall_utc":null,"source":"recorder","file":"recorder.jsonl","offset":120,"len":98,"line":2}"# +/// ); +/// +/// // and a line reads back as it was written +/// let back: TimelineEntry = serde_json::from_str(&serde_json::to_string(&entry)?)?; +/// assert_eq!(back, entry); +/// # Ok::<(), serde_json::Error>(()) +/// ``` +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct TimelineEntry { + /// Seconds since the first video frame (negative before it). + pub video_s: f64, + /// The record's time on the master clock, in nanoseconds. + pub mach_ns: u64, + /// RFC 3339 UTC with microseconds. + pub wall_utc: Option, + /// Which stream the record is from: `komorebi-log`, `events`, `recorder`, or an OS trace + /// source starting `oslog:`. + pub source: String, + /// The process the record is about, where it has one: an OS trace record's `processID`, or the + /// process id carried by a window manager event. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub pid: Option, + /// Raw file, relative to the session directory. + pub file: String, + /// The byte offset of the start of the record in `file`. + pub offset: u64, + /// How many bytes the record is in `file`, including its line terminator. + pub len: u64, + /// 1-based line number in the raw file. + pub line: u64, + /// The subscriber event sequence number, for `events` records. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub seq: Option, +} + +/// A timeline entry together with the raw text it points at. +/// +/// A query returns these. Serialized, a record is its entry's fields followed by `text`. +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct Record { + /// The index entry. + #[serde(flatten)] + pub entry: TimelineEntry, + /// The raw record, rendered for reading (see [`render`]). + pub text: String, +} + +/// Compact in-memory form used only while building. +struct Pending { + mach_ns: u64, + source: u32, + file: u32, + pid: Option, + offset: u64, + len: u64, + line: u64, + seq: Option, +} + +#[derive(Default)] +struct Interner { + names: Vec, + ids: HashMap, +} + +impl Interner { + fn id(&mut self, name: &str) -> u32 { + if let Some(id) = self.ids.get(name) { + return *id; + } + + let id = self.names.len() as u32; + self.names.push(name.to_string()); + self.ids.insert(name.to_string(), id); + id + } +} + +/// What [`build`] put in the index. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct BuildStats { + /// How many entries the index has. + pub entries: u64, + /// How many of those are from each source, by source name. A source with no entries is not + /// listed. + pub by_source: BTreeMap, +} + +fn wall_utc(clock: &ClockMap, mach_ns: u64) -> Option { + let wall_us = clock.mach_to_wall(mach_ns)?; + format_wall_us(wall_us) +} + +/// Returns a wall clock time as RFC 3339 UTC with microseconds and a `Z`, or `None` if it is +/// beyond what can be represented as a date. +/// +/// The argument is in microseconds since the Unix epoch, as `wall_us` is throughout a session. This +/// is the form of `wall_utc` in the index. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::timeline::format_wall_us; +/// +/// assert_eq!( +/// format_wall_us(1_800_000_000_250_000).as_deref(), +/// Some("2027-01-15T08:00:00.250000Z") +/// ); +/// assert_eq!(format_wall_us(0).as_deref(), Some("1970-01-01T00:00:00.000000Z")); +/// assert_eq!(format_wall_us(i64::MAX), None); +/// ``` +#[must_use] +pub fn format_wall_us(wall_us: i64) -> Option { + DateTime::::from_timestamp_micros(wall_us) + .map(|time| time.format("%Y-%m-%dT%H:%M:%S%.6fZ").to_string()) +} + +/// Which timeline source an unknown file under `oslog/` belongs to, from its name alone. Used for +/// hand-added files and when the manifest does not list a stream. +fn source_for_oslog_file(relative: &str) -> String { + let name = relative.strip_prefix("oslog/").unwrap_or(relative); + match name { + "komorebi.ndjson" => "oslog:komorebi".to_string(), + _ if name.starts_with("komorebi-") && name.ends_with(".ndjson") => { + "oslog:komorebi".to_string() + } + "system.ndjson" => "oslog:system".to_string(), + "eventlog.ndjson" => "oslog:eventlog".to_string(), + "all.ndjson" => "oslog:all".to_string(), + _ => { + let stem = name + .strip_prefix("apps/") + .unwrap_or(name) + .trim_end_matches(".ndjson"); + let exe = stem.rsplit_once('-').map_or(stem, |(exe, _pid)| exe); + format!("oslog:app:{exe}") + } + } +} + +fn list_oslog_files(session: &Session) -> Vec { + let mut files = Vec::new(); + for sub in ["oslog", "oslog/apps"] { + let Ok(entries) = std::fs::read_dir(session.path(sub)) else { + continue; + }; + + for entry in entries.flatten() { + let name = entry.file_name().to_string_lossy().into_owned(); + if name.ends_with(".ndjson") { + files.push(format!("{sub}/{name}")); + } + } + } + + files.sort(); + files +} + +/// Builds `timeline.jsonl` from the raw files and the manifest. +/// +/// Every raw file the session has is read (see the sources in the [module docs](self#the-sources)), +/// each record is given its time on the master clock, and the entries are written sorted, replacing +/// any existing index. A raw file the session does not have is skipped, so a session with no +/// events, say, has no `events` entries. The raw files are only read. The index is written to +/// `timeline.jsonl.tmp` and renamed over `timeline.jsonl`, so the old index stays whole until the +/// new one is. +/// +/// Building twice from the same raw files and manifest gives the same index (the test +/// `reindex_is_idempotent_and_recovers_a_deleted_timeline`). +/// +/// # Errors +/// +/// Returns an error if +/// +/// * the manifest cannot be read (see [`Session::manifest`]); +/// * a raw file that exists cannot be read; +/// * `timeline.jsonl.tmp` cannot be created or written; +/// * the finished file cannot be renamed over `timeline.jsonl`. +/// +/// # Example +/// +/// See the [module example](self#example), which builds the index of a session and reads it back. +pub fn build(session: &Session) -> eyre::Result { + let manifest = session.manifest()?; + let clock = ClockMap::new(manifest.anchors.clone()); + let mut sources = Interner::default(); + let mut files = Interner::default(); + let mut pending: Vec = Vec::new(); + + // komorebi's own log: UTC wall clock -> mach via the anchors + let log_path = session.path("komorebi.log"); + if log_path.is_file() { + let bytes = std::fs::read(&log_path)?; + let source = sources.id(SOURCE_KOMOREBI_LOG); + let file = files.id("komorebi.log"); + for line in komorebi_log::index_lines(&bytes) { + let Some(timestamp) = line.timestamp else { + continue; + }; + let Some(mach_ns) = clock.wall_to_mach(timestamp.timestamp_micros()) else { + continue; + }; + + pending.push(Pending { + mach_ns, + source, + file, + pid: None, + offset: line.offset, + len: line.len, + line: line.number, + seq: None, + }); + } + } + + // subscriber events: stamped on the mach clock at receipt + let events_path = session.path("events.jsonl"); + if events_path.is_file() { + let source = sources.id(SOURCE_EVENTS); + let file = files.id("events.jsonl"); + let mut reader = BufReader::new(File::open(&events_path)?); + let mut buffer = String::new(); + let (mut offset, mut number) = (0_u64, 0_u64); + loop { + buffer.clear(); + let read = reader.read_line(&mut buffer)?; + if read == 0 { + break; + } + + number += 1; + if let Ok(row) = serde_json::from_str::(&buffer) { + pending.push(Pending { + mach_ns: row.recv_mach_ns, + source, + file, + pid: row + .event + .as_ref() + .and_then(managed_apps::event_pid) + .map(i64::from), + offset, + len: read as u64, + line: number, + seq: Some(row.seq), + }); + } + + offset += read as u64; + } + } + + // incidents (display changes, sleep/wake, restarts): stamped on the mach clock when noticed + let incidents_path = session.path(INCIDENTS_FILE); + if incidents_path.is_file() { + let source = sources.id(SOURCE_RECORDER); + let file = files.id(INCIDENTS_FILE); + let mut reader = BufReader::new(File::open(&incidents_path)?); + let mut buffer = String::new(); + let (mut offset, mut number) = (0_u64, 0_u64); + loop { + buffer.clear(); + let read = reader.read_line(&mut buffer)?; + if read == 0 { + break; + } + + number += 1; + if let Ok(incident) = serde_json::from_str::(&buffer) { + pending.push(Pending { + mach_ns: incident.mach_ns, + source, + file, + pid: None, + offset, + len: read as u64, + line: number, + seq: None, + }); + } + + offset += read as u64; + } + } + + // unified log streams: already on the mach clock + let manifest_sources: HashMap<&str, &str> = manifest + .oslog + .iter() + .map(|info| (info.spec.file.as_str(), info.spec.source.as_str())) + .collect(); + + for relative in list_oslog_files(session) { + let source_name = manifest_sources.get(relative.as_str()).map_or_else( + || source_for_oslog_file(&relative), + |source| (*source).to_string(), + ); + let source = sources.id(&source_name); + let file = files.id(&relative); + + let mut reader = BufReader::with_capacity(256 * 1024, File::open(session.path(&relative))?); + let mut buffer = Vec::new(); + let (mut offset, mut number) = (0_u64, 0_u64); + loop { + buffer.clear(); + let read = reader.read_until(b'\n', &mut buffer)?; + if read == 0 { + break; + } + + number += 1; + // converted with the session's own timebase, not this machine's: a session recorded on + // one OS is read on another + if let Some(mach_ns) = oslog::extract_time_ns(&buffer, manifest.timebase) { + pending.push(Pending { + mach_ns, + source, + file, + pid: extract_pid(&buffer), + offset, + len: read as u64, + line: number, + seq: None, + }); + } + + offset += read as u64; + } + } + + pending.sort_by_key(|entry| (entry.mach_ns, entry.source, entry.file, entry.offset)); + + let path = session.path(TIMELINE_FILE); + let temporary = session.path(format!("{TIMELINE_FILE}.tmp")); + let mut writer = BufWriter::new( + File::create(&temporary) + .wrap_err_with(|| format!("could not create {}", temporary.display()))?, + ); + + let mut stats = BuildStats::default(); + for entry in &pending { + let source = &sources.names[entry.source as usize]; + let row = TimelineEntry { + video_s: manifest.video_seconds(entry.mach_ns), + mach_ns: entry.mach_ns, + wall_utc: wall_utc(&clock, entry.mach_ns), + source: source.clone(), + pid: entry.pid, + file: files.names[entry.file as usize].clone(), + offset: entry.offset, + len: entry.len, + line: entry.line, + seq: entry.seq, + }; + + writeln!(writer, "{}", serde_json::to_string(&row)?)?; + stats.entries += 1; + *stats.by_source.entry(source.clone()).or_default() += 1; + } + + writer.flush()?; + drop(writer); + std::fs::rename(&temporary, &path)?; + Ok(stats) +} + +/// Pull `"processID":` out of a raw ndjson line. +fn extract_pid(line: &[u8]) -> Option { + const KEY: &[u8] = b"\"processID\":"; + let start = line.windows(KEY.len()).position(|window| window == KEY)? + KEY.len(); + let digits: Vec = line[start..] + .iter() + .copied() + .take_while(|byte| byte.is_ascii_digit() || *byte == b'-') + .collect(); + + std::str::from_utf8(&digits).ok()?.parse().ok() +} + +/// Narrowing for queries: which sources, and which application, to keep. +/// +/// The default keeps every record. When both fields are set, a record must pass both. +/// +/// # Example +/// +/// The two fields combine, and `app` keeps an application's OS trace records only, never the +/// komorebi log or events that merely mention it: +/// +/// ```rust +/// use komorebi_recorder::timeline::Filter; +/// +/// // the OS trace of one application, by exe name (any case) or by process id +/// let ghostty = Filter { app: Some("ghostty".to_string()), sources: vec![] }; +/// let by_pid = Filter { app: Some("111".to_string()), ..Filter::default() }; +/// +/// // two sources: komorebi's log, and the OS trace of the komorebi process +/// let two = Filter { +/// sources: vec!["komorebi-log".to_string(), "oslog:komorebi".to_string()], +/// ..Filter::default() +/// }; +/// # let _ = (ghostty, by_pid, two); +/// ``` +/// +/// The behavior is covered by the tests `source_filter_supports_prefixes` and +/// `app_filter_returns_only_that_apps_records`. +#[derive(Debug, Clone, Default)] +pub struct Filter { + /// An app's exe name (case-insensitive) or a pid. + /// + /// Keeps only OS trace records (sources starting `oslog:`) of that app: those with its process + /// id, or whose source is `oslog:app:`. A name is looked up in the manifest's apps to + /// find its process ids. + pub app: Option, + /// Sources to keep: `komorebi-log`, `events`, `oslog` (all OS trace), `oslog:komorebi`, + /// `oslog:system`, `oslog:app` (all apps) or `oslog:app:`. Empty keeps everything. + /// + /// A name matches a source if it equals it, ignoring case, or is a prefix of it that ends + /// where the source has a `:`. So `oslog` keeps `oslog:system`, but `osl` keeps nothing. + pub sources: Vec, +} + +fn source_matches(source: &str, wanted: &str) -> bool { + source.eq_ignore_ascii_case(wanted) + || source.get(..wanted.len()).is_some_and(|prefix| { + prefix.eq_ignore_ascii_case(wanted) + && source.as_bytes().get(wanted.len()) == Some(&b':') + }) +} + +/// The pids and source labels an `--app` argument refers to, using the manifest's app list. +fn resolve_app(manifest: &Manifest, app: &str) -> (Vec, String) { + if let Ok(pid) = app.parse::() { + return (vec![pid], String::new()); + } + + let pids = manifest + .apps + .iter() + .filter(|record| record.exe.eq_ignore_ascii_case(app)) + .map(|record| i64::from(record.pid)) + .collect(); + + (pids, format!("oslog:app:{app}")) +} + +impl Filter { + fn accepts(&self, entry: &TimelineEntry, app: Option<&(Vec, String)>) -> bool { + if !self.sources.is_empty() + && !self + .sources + .iter() + .any(|wanted| source_matches(&entry.source, wanted)) + { + return false; + } + + if let Some((pids, source)) = app { + let by_pid = entry.pid.is_some_and(|pid| pids.contains(&pid)); + let by_source = !source.is_empty() && entry.source.eq_ignore_ascii_case(source); + // `--app` is "only this app's records": the komorebi log and events are not that + // app's, even though events may mention its pid + let is_app_data = entry.source.starts_with("oslog:"); + return is_app_data && (by_pid || by_source); + } + + true + } +} + +fn read_entry_line( + reader: &mut BufReader, + buffer: &mut String, +) -> eyre::Result> { + buffer.clear(); + let read = reader.read_line(buffer)?; + if read == 0 { + return Ok(None); + } + + let entry: TimelineEntry = serde_json::from_str(buffer.trim_end()) + .wrap_err("timeline.jsonl contains an invalid line; run `reindex`")?; + Ok(Some((entry, read as u64))) +} + +/// The byte offset of the first line whose `mach_ns` is `>= target`, or the file length. +fn lower_bound(file: &mut BufReader, size: u64, target: u64) -> eyre::Result { + let mut buffer = String::new(); + + // the first line start at or after `position` + let line_start_at_or_after = |file: &mut BufReader, position: u64| -> eyre::Result { + if position == 0 { + return Ok(0); + } + + file.seek(SeekFrom::Start(position - 1))?; + let mut skipped = Vec::new(); + let read = file.read_until(b'\n', &mut skipped)?; + Ok(position - 1 + read as u64) + }; + + let (mut low, mut high) = (0_u64, size); + while low < high { + let middle = low + (high - low) / 2; + let start = line_start_at_or_after(file, middle)?; + if start >= high { + high = middle; + continue; + } + + file.seek(SeekFrom::Start(start))?; + match read_entry_line(file, &mut buffer)? { + Some((entry, length)) => { + if entry.mach_ns < target { + low = start + length; + } else { + high = start; + } + } + None => high = middle, + } + } + + Ok(low) +} + +/// Raw files opened on demand while rendering records. +struct RawFiles<'a> { + session: &'a Session, + open: HashMap, +} + +impl<'a> RawFiles<'a> { + fn new(session: &'a Session) -> Self { + Self { + session, + open: HashMap::new(), + } + } + + fn read(&mut self, entry: &TimelineEntry) -> eyre::Result { + if !self.open.contains_key(&entry.file) { + let path = self.session.path(&entry.file); + let file = + File::open(&path).wrap_err_with(|| format!("could not open {}", path.display()))?; + self.open.insert(entry.file.clone(), file); + } + + let file = self + .open + .get_mut(&entry.file) + .ok_or_else(|| eyre::Report::msg("raw file vanished"))?; + file.seek(SeekFrom::Start(entry.offset))?; + let mut bytes = vec![0_u8; entry.len as usize]; + file.read_exact(&mut bytes)?; + Ok(String::from_utf8_lossy(&bytes) + .trim_end_matches(['\n', '\r']) + .to_string()) + } +} + +const EVENT_TEXT_LIMIT: usize = 400; + +/// Renders a raw record for reading: one line of text for the entry `entry`, whose raw text is +/// `raw`. +/// +/// What it does depends on the entry's source: +/// +/// | Source | Rendered as | +/// |---|---| +/// | `komorebi-log` | the raw line with ANSI escapes removed ([`strip_ansi`]) | +/// | `recorder` | `: ` | +/// | `events` | `# `, then ` state=states/.json` if the event stored a state (the id is zero padded to 6 digits) | +/// | anything else, the OS trace | `