feat(logq): query komorebi's log by field, with counts and group-by

logq <session> 'level=ERROR and hwnd=0x77179C' filters komorebi.log by
level, target, message, line, the span chain, the handled command and
event, or any span field, with and/or/parentheses, = != ~ !~, --count,
--group-by, --from/--to and a paged logq/1 envelope whose hits carry log:N
references. hwnd compares equal in decimal and hex. logparse keeps the
span chain as written (Line::chain).
This commit is contained in:
LGUG2Z committed 2026-10-28 16:24:29 -07:00
1 parent f3811fc24f
commit 1f6e4cef05
9 files changed
+1385 -7

No files matched your search

+1
View File
@@ -115,6 +115,7 @@ and `event:12.end` when it finished.
| `trace event:N` | One event end to end: what its handler logged, with the source statement for each line, what other threads logged meanwhile, and every change with who made it (see below). `--os` adds the OS trace around it: komorebi's own calls into the OS, the system and each application, split into while the handler ran and after |
| `window ID\|TEXT` | One window's life: when it appeared, moved, was parked off screen, was really somewhere else, and which event did each |
| `code event:N`, `code log:N` | The line of komorebi's source that wrote a log line, with the code around it |
| `logq QUERY` | Query komorebi's log by field, with no escape codes or span prefixes to strip: `level=ERROR and message~ghost`, `hwnd=0x77179C` (decimal and hex are the same window), `command=MoveWindow`; `--count`, `--group-by FIELD`, `--from`/`--to`, `--spans` |
| `search TEXT` | Where a word appears: komorebi's log, events, incidents, annotations (and `--oslog` for the macOS trace) |
| `changes` | When and where on each display the picture changed, and which events fall inside |
| `sheet` | A contact sheet image of frames with times, events and the bug region marked |
+46 -7
View File
@@ -112,6 +112,13 @@ pub struct Line {
/// The spans the code was inside, outermost first. Empty for a line logged outside any span,
/// such as one from another thread.
pub spans: Vec<Span>,
/// The span chain as the log wrote it, ANSI removed: `process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right}`.
/// Unlike [`Line::spans`] it keeps a span's braces exactly, so a span that is not `key=value`
/// fields (the argument of `process_command`) is still there. Empty when `spans` is. Not part
/// of the serialized line.
#[serde(skip)]
#[schemars(skip)]
pub chain: String,
/// The module that logged, e.g. `komorebi::container`. `None` for a continuation and for a line
/// in which none was found.
pub target: Option<String>,
@@ -216,6 +223,7 @@ pub fn parse_line(
continuation,
level: None,
spans: Vec::new(),
chain: String::new(),
target: None,
message: text.to_string(),
};
@@ -236,18 +244,20 @@ pub fn parse_line(
continuation: false,
level: None,
spans: Vec::new(),
chain: String::new(),
target: None,
message: after_time.to_string(),
};
};
let (spans, target, message) = parse_body(body.trim_start());
let (spans, chain, target, message) = parse_body(body.trim_start());
Line {
number,
wall_us: time.map(|time| time.timestamp_micros()),
continuation: false,
level: Some(level),
spans,
chain,
target,
message,
}
@@ -330,8 +340,10 @@ fn parse_fields(text: &str) -> Vec<(String, String)> {
}
/// The span chain, target and message of the part of a line after its level.
fn parse_body(body: &str) -> (Vec<Span>, Option<String>, String) {
fn parse_body(body: &str) -> (Vec<Span>, String, Option<String>, String) {
let mut spans = Vec::new();
// each span as written, parallel to `spans`
let mut raws: Vec<&str> = Vec::new();
let mut cursor = body;
// spans: `name`, `name{fields}`, joined by `:`; the chain ends at `: `
@@ -348,13 +360,17 @@ fn parse_body(body: &str) -> (Vec<Span>, Option<String>, String) {
break;
}
let (fields, tail) = if after.starts_with('{') {
let (fields, tail, raw) = if after.starts_with('{') {
match braced(after) {
Some((inside, tail)) => (parse_fields(inside), tail),
Some((inside, tail)) => (
parse_fields(inside),
tail,
&cursor[..cursor.len() - tail.len()],
),
None => break,
}
} else {
(Vec::new(), after)
(Vec::new(), after, name)
};
if let Some(rest) = tail.strip_prefix(": ") {
@@ -362,6 +378,7 @@ fn parse_body(body: &str) -> (Vec<Span>, Option<String>, String) {
name: name.to_string(),
fields,
});
raws.push(raw);
cursor = rest;
break;
}
@@ -371,6 +388,7 @@ fn parse_body(body: &str) -> (Vec<Span>, Option<String>, String) {
name: name.to_string(),
fields,
});
raws.push(raw);
cursor = rest;
continue;
}
@@ -390,6 +408,7 @@ fn parse_body(body: &str) -> (Vec<Span>, Option<String>, String) {
{
return (
spans,
raws.join(":"),
Some(target.to_string()),
cursor[target_len + 1..].to_string(),
);
@@ -399,10 +418,11 @@ fn parse_body(body: &str) -> (Vec<Span>, Option<String>, String) {
if spans.last().is_some_and(|last| last.fields.is_empty())
&& let Some(last) = spans.pop()
{
return (spans, Some(last.name), cursor.to_string());
raws.pop();
return (spans, raws.join(":"), Some(last.name), cursor.to_string());
}
(spans, None, cursor.to_string())
(spans, raws.join(":"), None, cursor.to_string())
}
#[cfg(test)]
@@ -416,6 +436,25 @@ mod tests {
parse_line(1, &strip_ansi(text), time, time.is_none())
}
#[test]
fn the_chain_keeps_each_span_as_written() {
let parsed = line(
"2026-10-26T23:09:16.688494Z INFO process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right}: komorebi::window_manager: moving",
);
assert_eq!(
parsed.chain,
"process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right}"
);
// a lone word before the message is a target, so it is not part of the chain
let lone = line("2026-10-26T23:09:16.688494Z INFO a{x=1}:komorebi: hello");
assert_eq!(lone.chain, "a{x=1}");
assert_eq!(lone.target.as_deref(), Some("komorebi"));
let bare = line("2026-10-26T23:09:16.688494Z INFO komorebi::x: hello");
assert_eq!(bare.chain, "");
}
#[test]
fn a_handler_header_has_one_span_a_target_and_a_message() {
let parsed = line(
File diff suppressed because it is too large. Load diff
+1
View File
@@ -26,6 +26,7 @@ pub mod history;
pub mod ids;
pub mod invariants;
pub mod logparse;
pub mod logq;
pub mod lookup;
pub mod os_trace;
pub mod overview;
@@ -20,6 +20,7 @@ use super::changes::ChangesData;
use super::code::CodeData;
use super::envelope::Envelope;
use super::history::HistoryData;
use super::logq::LogqData;
use super::overview::OverviewData;
use super::search::SearchData;
use super::sheet::SheetData;
@@ -94,6 +95,11 @@ pub const ALL: &[Entry] = &[
about: "`search`: where a word appears in the recording",
schema: of::<SearchData>,
},
Entry {
name: "logq/1",
about: "`logq`: lines of komorebi's log matching a field query, counted or grouped",
schema: of::<LogqData>,
},
Entry {
name: "changes/1",
about: "`changes`: when and where the picture changed on each display",
+116
View File
@@ -0,0 +1,116 @@
//! `logq`: structured queries over a session's `komorebi.log` (see [`crate::analysis::logq`]).
//!
//! With `--json` the answer is the `logq/1` envelope. A page cut short by `--limit` sets
//! `truncated` and a `next_cursor`, which `--cursor` takes back. `--count` prints only the number
//! of matching lines.
//!
//! Covered by `tests/logq.rs`, which runs the command through the real binary.
use super::print_json;
use crate::analysis::Analysis;
use crate::analysis::budget::Budget;
use crate::analysis::envelope::Envelope;
use crate::analysis::logq::LogqQuery;
use crate::analysis::logq::SCHEMA_LOGQ;
use crate::analysis::logq::logq_text;
use clap::Args;
use color_eyre::eyre;
use std::path::PathBuf;
use std::time::Duration;
/// The arguments of `logq`.
#[derive(Args, Debug)]
pub struct LogqArgs {
/// Session directory
pub session: PathBuf,
/// Predicates joined by `and`/`or`: `level=ERROR and message~"ghost"`, `hwnd=0x77179C`,
/// `command=MoveWindow`. Operators: = != ~ !~. Fields: level, target, message, line, spans,
/// command, event, or any span field (hwnd, winevent, direction, ...)
pub query: String,
/// Only after this moment (video time, `log:N`, `event:N`, ...)
#[arg(long, value_name = "TIME")]
pub from: Option<String>,
/// Only before this moment
#[arg(long, value_name = "TIME")]
pub to: Option<String>,
/// Most hits (or groups) to print (0 for all)
#[arg(long, default_value_t = 50)]
pub limit: usize,
/// Continue after this many hits (from a truncated answer's `next_cursor`)
#[arg(long, value_name = "N")]
pub cursor: Option<usize>,
/// Print only how many lines match
#[arg(long, conflicts_with = "group_by")]
pub count: bool,
/// Count the matching lines by each distinct value of this field, most common first
#[arg(long, value_name = "FIELD")]
pub group_by: Option<String>,
/// Show each hit's span chain in text output (cut to 100 characters)
#[arg(long)]
pub spans: bool,
/// Give up after this many milliseconds
#[arg(long, value_name = "MS")]
pub budget_ms: Option<u64>,
/// Machine-readable JSON output
#[arg(long)]
pub json: bool,
}
pub(super) fn logq(args: &LogqArgs) -> eyre::Result<()> {
let analysis = Analysis::open(&args.session)?;
let moment = |text: &Option<String>| -> eyre::Result<Option<u64>> {
text.as_deref()
.map(|text| analysis.resolve(text).map(|resolved| resolved.mach_ns))
.transpose()
};
let mut budget = Budget::unlimited().reading_at_most(512 * 1024 * 1024);
if let Some(ms) = args.budget_ms {
budget = budget.within(Duration::from_millis(ms));
}
let limit = super::limit(args.limit);
let skip = args.cursor.unwrap_or(0);
let data = analysis.logq(
&LogqQuery {
query: args.query.clone(),
from_mach_ns: moment(&args.from)?,
to_mach_ns: moment(&args.to)?,
group_by: args.group_by.clone(),
skip,
limit,
count_only: args.count,
},
&budget,
)?;
let (returned, total) = if data.group_by.is_some() {
(data.groups.len(), data.distinct)
} else {
(data.hits.len(), data.matching)
};
let truncated = !args.count && limit.is_some() && skip + returned < total;
let next_cursor = truncated.then(|| (skip + returned).to_string());
if args.json {
let mut warnings = analysis.warnings();
warnings.extend(data.notes.clone());
let mut envelope = Envelope::ok(SCHEMA_LOGQ, data).warnings(warnings);
if truncated {
envelope = envelope.truncated(next_cursor);
}
return print_json(&envelope);
}
print!("{}", logq_text(&data, args.count, args.spans));
for note in &data.notes {
eprintln!("note: {note}");
}
if let Some(cursor) = next_cursor {
eprintln!(
"... {} of {total} shown; continue with --cursor {cursor}",
returned
);
}
Ok(())
}
+6
View File
@@ -9,6 +9,7 @@ mod agent;
mod annotate;
mod doctor;
mod investigate;
mod logq;
mod query;
mod record;
mod video;
@@ -38,6 +39,7 @@ pub use investigate::EventsArgs;
pub use investigate::StateArgs;
pub use investigate::TraceArgs;
pub use investigate::WindowArgs;
pub use logq::LogqArgs;
pub use query::AtArgs;
pub use query::FilterArgs;
pub use query::FramesArgs;
@@ -96,6 +98,8 @@ pub enum Command {
Overview(OverviewArgs),
/// Where a word appears: komorebi's log, events, incidents, annotations, optionally the OS trace
Search(SearchArgs),
/// Query komorebi's log by field: level, target, message, span fields (hwnd, event, ...), with counts and group-by
Logq(LogqArgs),
/// How to investigate a recording, for an agent
Guide(GuideArgs),
/// The JSON Schema of a command's `--json` output
@@ -175,6 +179,7 @@ impl Command {
Self::Brief(args) => args.json,
Self::Overview(args) => args.json,
Self::Search(args) => args.json,
Self::Logq(args) => args.json,
Self::Guide(args) => args.json,
Self::State(args) => args.json,
Self::Diff(args) => args.json,
@@ -234,6 +239,7 @@ pub fn run(command: Command) -> eyre::Result<()> {
Command::Brief(args) => agent::brief(&args),
Command::Overview(args) => agent::overview(&args),
Command::Search(args) => agent::search(&args),
Command::Logq(args) => logq::logq(&args),
Command::Guide(args) => agent::guide(&args),
Command::Schema(args) => agent::schema(&args),
Command::State(args) => investigate::state(&args),
+6
View File
@@ -57,6 +57,12 @@ locations as hints.
with the code around it. `ambiguous` and `generic` matches say so: do not pin a cause on one.
7. **Anything else.** `search <text>` across the log, events, incidents and annotations
(`--oslog` adds the OS trace, where the recording has one); `at`, `range` and `summary` read the raw timeline.
To query komorebi's log by field instead of grepping it, use `logq <session> 'level=ERROR and hwnd=0x77179C'`
(`and`/`or`, `= != ~ !~`; `command`, `event` and any span field; `--count`, `--group-by <field>`);
each hit's `log:N` goes to `at`, `trace` and `annotate --ref`.
To query komorebi's log by field instead of grepping it, use `logq <session> 'level=ERROR and hwnd=0x77179C'`
(`and`/`or`, `= != ~ !~`; `command`, `event` and any span field; `--count`, `--group-by <field>`);
each hit's `log:N` goes to `at`, `trace` and `annotate --ref`.
## 3. Facts about the data that change what it means
+184
View File
@@ -0,0 +1,184 @@
//! `logq` through the real binary: field queries over komorebi's log, counts, group-by, the JSON
//! envelope and what a bad query says.
use komorebi_recorder::testkit::SessionBuilder;
use serde_json::Value;
use std::process::Command;
use std::process::Output;
fn recorder(args: &[&str]) -> Output {
Command::new(env!("CARGO_BIN_EXE_komorebi-recorder"))
.args(args)
.output()
.expect("run komorebi-recorder")
}
fn text(args: &[&str]) -> String {
let output = recorder(args);
assert!(
output.status.success(),
"{args:?}: {}",
String::from_utf8_lossy(&output.stderr)
);
String::from_utf8_lossy(&output.stdout).into_owned()
}
fn json(args: &[&str]) -> Value {
serde_json::from_str(&text(args)).expect("JSON")
}
fn session(name: &str) -> String {
let (session, _) = SessionBuilder::new(name)
.log(1.0, "INFO", "process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right}: komorebi::window_manager: moving container")
.log(2.0, "WARN", "process_event{event=\"Show\" winevent=\"ObjectShow\" hwnd=7804828}: komorebi::process_event: ghost tile for 0x77179c")
.log(3.389, "ERROR", "process_event{event=\"Show\" winevent=\"ObjectShow\" hwnd=7804828}:update{follow=true}: komorebi::workspace: Ghost window dropped")
.log(4.0, "INFO", "process_event{event=\"Hide\" winevent=\"ObjectHide\" hwnd=99}: komorebi::process_event: hidden")
.log(5.0, "DEBUG", "komorebi::reaper: reaping")
.build();
session.dir.display().to_string()
}
#[test]
fn lines_are_found_by_field_and_listed_with_references() {
let dir = session("logq-fields");
let found = text(&["logq", &dir, "level=WARN or level=ERROR"]);
let lines: Vec<&str> = found.lines().collect();
assert_eq!(lines.len(), 2, "{found}");
assert!(
lines[0].starts_with("log:2 00:02.000 WARN ghost tile"),
"{found}"
);
assert!(
lines[1].starts_with("log:3 00:03.389 ERROR Ghost window"),
"{found}"
);
// hwnd is the same window in decimal and hex
for query in ["hwnd=7804828", "hwnd=0x77179C"] {
assert_eq!(
text(&["logq", &dir, query, "--count"]).trim(),
"2",
"{query}"
);
}
assert_eq!(
text(&["logq", &dir, "command=MoveWindow", "--count"]).trim(),
"1"
);
assert_eq!(
text(&["logq", &dir, "direction=Right and level=info", "--count"]).trim(),
"1"
);
assert_eq!(
text(&["logq", &dir, "message~ghost", "--count"]).trim(),
"2"
);
assert_eq!(
text(&["logq", &dir, "message~\"(?-i)^ghost\"", "--count"]).trim(),
"1"
);
assert_eq!(
text(&["logq", &dir, "event=Show and not=x", "--count"]).trim(),
"0"
);
// the span chain can be shown, and is trimmed to a line
let with_spans = text(&["logq", &dir, "command=MoveWindow", "--spans"]);
assert!(
with_spans.contains("process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right} moving container"),
"{with_spans}"
);
}
#[test]
fn counting_grouping_and_ranges() {
let dir = session("logq-group");
let grouped = text(&["logq", &dir, "hwnd~.", "--group-by", "hwnd"]);
assert_eq!(grouped, "2 7804828\n1 99\n");
let levels = text(&["logq", &dir, "message~.", "--group-by", "level"]);
assert!(levels.starts_with("2 INFO\n"), "{levels}");
let ranged = text(&[
"logq",
&dir,
"message~.",
"--from",
"2.5",
"--to",
"4",
"--count",
]);
assert_eq!(ranged.trim(), "2");
}
#[test]
fn json_is_an_envelope_that_pages() {
let dir = session("logq-json");
let page = json(&["logq", &dir, "message~.", "--limit", "2", "--json"]);
assert_eq!(page["ok"], true);
assert_eq!(page["schema"], "logq/1");
assert_eq!(page["truncated"], true);
assert_eq!(page["next_cursor"], "2");
assert_eq!(page["data"]["matching"], 5);
assert_eq!(page["data"]["hits"].as_array().expect("hits").len(), 2);
assert_eq!(page["data"]["hits"][0]["reference"], "log:1");
assert_eq!(page["data"]["hits"][0]["source"], "komorebi-log");
assert_eq!(page["data"]["hits"][0]["level"], "INFO");
assert_eq!(
page["data"]["hits"][0]["spans"],
"process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right}"
);
let next = json(&[
"logq",
&dir,
"message~.",
"--limit",
"2",
"--cursor",
"2",
"--json",
]);
assert_eq!(next["data"]["hits"][0]["reference"], "log:3");
let grouped = json(&["logq", &dir, "hwnd~.", "--group-by", "hwnd", "--json"]);
assert_eq!(grouped["data"]["groups"][0]["value"], "7804828");
assert_eq!(grouped["data"]["groups"][0]["count"], 2);
// a field no line has is said, not silently empty
let typo = json(&["logq", &dir, "hwdn=1", "--json"]);
assert_eq!(typo["data"]["matching"], 0);
assert!(typo["warnings"].to_string().contains("hwdn"), "{typo}");
// the references are the ones `at` and `trace` take
let at = recorder(&["at", &dir, "3.389"]);
assert!(at.status.success());
let schema = text(&["schema", "logq/1"]);
assert!(schema.contains("matching"));
}
#[test]
fn a_bad_query_is_a_usage_error_with_a_hint() {
let dir = session("logq-bad");
for query in ["level ERROR", "", "message~\"(\""] {
let output = recorder(&["logq", &dir, query, "--json"]);
assert_eq!(output.status.code(), Some(2), "{query:?}");
let envelope: Value = serde_json::from_slice(&output.stdout).expect("envelope");
assert_eq!(envelope["ok"], false);
assert_eq!(envelope["error"]["kind"], "usage");
assert!(
envelope["error"]["hint"]
.as_str()
.unwrap_or_default()
.contains("hwnd"),
"{envelope}"
);
}
}