From c4e505d9212125354bc80cb6cd747d162be0b82e Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Thu, 29 Oct 2026 11:42:03 -0700 Subject: [PATCH] docs(events): the komorebi time column and which flavors' logs it is checked for --- docs/usage/investigating-a-recording.md | 4 ++++ docs/usage/recording-a-bug-repro.md | 8 ++++++++ komorebi-recorder/src/guide.md | 4 ++++ 3 files changed, 16 insertions(+) diff --git a/docs/usage/investigating-a-recording.md b/docs/usage/investigating-a-recording.md index ad2095ec..2702f1f2 100644 --- a/docs/usage/investigating-a-recording.md +++ b/docs/usage/investigating-a-recording.md @@ -169,6 +169,10 @@ the same. `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. +- The `events` listing's time is one **komorebi time** per event: `p` when it is komorebi's pushed time, `r` when the log + has no pushed line and it is only the received time (the header says so; `--json` has `komorebi_time.source` and + `komorebi_time_note`). The received time is still given as `video_s`. The pushed line is checked only for komorebi for + Mac's log; for Windows and KDE it is unverified, so expect `r` there if the log lacks it. - 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 a13f4715..73a506a0 100644 --- a/docs/usage/recording-a-bug-repro.md +++ b/docs/usage/recording-a-bug-repro.md @@ -376,6 +376,14 @@ anchors sampled every 5 seconds during the recording and at every sleep, so cloc - subscriber events are stamped when the recorder receives them. komorebi sends the notification _after_ it has handled the event, so the stamp is when the handler **finished**; the `processing event` line in `komorebi.log` is when it began. + The `events` listing shows one **komorebi time** per event, so the two clocks are not mixed up: when komorebi pushed + the notification (`p`, from its DEBUG log line `pushed notification to subscriber:`), or, where the log has no such + line for the event, when the recorder received it (`r`). The fallback is stated in the listing's header and as + `komorebi_time_note` in `--json`, never silent. In JSON every event has `komorebi_time` with `source` (`pushed` or + `received`), `video_s`, `mach_ns` and `wall_utc`. The pushed line needs komorebi at `--log-level debug`. Matching it + to an event does not depend on the flavor, but it has only been checked against komorebi for Mac's log format and a + synthetic one; whether komorebi for Windows and for KDE log the line at all has not been checked against a + recording, and without it the listing falls back to `r`. `komorebi-recorder trace` ties the two together. `komorebi-recorder selftest` checks this on your machine: it records a rendered on-screen clock and compares the clock diff --git a/komorebi-recorder/src/guide.md b/komorebi-recorder/src/guide.md index b1edb10d..52e570bf 100644 --- a/komorebi-recorder/src/guide.md +++ b/komorebi-recorder/src/guide.md @@ -86,6 +86,10 @@ locations as hints. 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. +- The `events` listing's time is one **komorebi time** per event: `p` when it is komorebi's pushed time, `r` when the log + has no pushed line and it is only the received time (the header says so; `--json` has `komorebi_time.source` and + `komorebi_time_note`). The received time is still given as `video_s`. The pushed line is checked only for komorebi for + Mac's log; for Windows and KDE it is unverified, so expect `r` there if the log lacks it. - 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`,