From e908269db30712c3ddaeee28b1d2adb8c82b9fcf Mon Sep 17 00:00:00 2001 From: Jaroslav Bachorik Date: Sun, 15 Nov 2026 18:09:57 +0100 Subject: [PATCH] docs(jafar-perf): describe the fixed jfr_use/jfr_tsa time window and time-filter cost btraceio/jafar#206 made the startTime/endTime window of jfr_use and jfr_tsa work and stated its contract: nanoseconds from the recording's start, with an epoch-nanosecond timestamp also accepted. The latency skill showed the window with a bare and said nothing about jfr_tsa or how to confirm the result, so it now gives the contract and points at the three new timeWindow fields (recordingStartEpochNanos, startTimeEpochNanos, endTimeEpochNanos). The same change made JfrPath decode only the event types a query names and skip chunks that ended before a lower bound on startTime. The jfrpath skill named the time predicates without a signature; it now shows them and says which filters make a query cheaper on a large recording. The plugin still pins jfr-mcp 0.29.0, which predates the fix, so the latency skill also says how to recognise a result from such a server. Verified: check-tool-references.js passes against the pinned release, the latest release and a jar built from jafar main (37 tools each); validate-marketplace.sh passes; a stdio probe of the main build on test-ap.jfr returned the same 4296 samples for offset and epoch bounds, matching the jfr_query count for that window. Co-Authored-By: Claude Fable 5.2 --- plugins/jafar-perf/skills/jfrpath/SKILL.md | 33 +++++++++++++++++++++- plugins/jafar-perf/skills/latency/SKILL.md | 29 ++++++++++++++++++- 2 files changed, 60 insertions(+), 2 deletions(-) diff --git a/plugins/jafar-perf/skills/jfrpath/SKILL.md b/plugins/jafar-perf/skills/jfrpath/SKILL.md index 99bc68a..d6a49d0 100644 --- a/plugins/jafar-perf/skills/jfrpath/SKILL.md +++ b/plugins/jafar-perf/skills/jfrpath/SKILL.md @@ -27,7 +27,7 @@ events/jdk.FileRead[bytes>1000 and path~"/tmp/.*"] Operators: `=` `!=` `>` `>=` `<` `<=` `~` (regex). Combine with `and`, `or`, `not` and parentheses. Functions usable inside a filter: `contains`, `startsWith`, `endsWith`, `matches(path,"re"[,"i"])`, `exists`, `empty`, `between(path,a,b)`, `len(path)`, and the -time predicates `before`, `after`, `on`. +time predicates `before`, `after`, `on` (see "Time filters" below). Filters can be interleaved at any segment: @@ -60,6 +60,37 @@ events/jdk.JavaMonitorEnter[duration>1ms] | count() A bare number in a duration field is nanoseconds: `[duration>10000000]` is the same 10 ms. There is deliberately no `m` suffix for minutes, because `M` already means mebibytes. +### Time filters + +An event's `startTime` is epoch nanoseconds. Compare it with a number, or use the time +predicates with a datetime string: + +``` +events/jdk.ExecutionSample[after(startTime, "2024-08-13T16:00:00Z")] +events/jdk.ExecutionSample[before(startTime, "2024-08-13T17:00:00Z")] +events/jdk.ExecutionSample[between(startTime, "2024-08-13T16:00:00Z", "2024-08-13T17:00:00Z")] +events/jdk.ExecutionSample[on(startTime, "2024-08-13")] +events/jdk.JavaMonitorEnter[startTime>= and duration>10ms] +``` + +`between` is inclusive. A datetime without `Z` or an offset, and the date given to `on`, are +read in the server's local timezone — write the offset when the hour matters. + +These are JfrPath filters on epoch time. The `startTime` and `endTime` *parameters* of +`jfr_use` and `jfr_tsa` are a different thing — nanoseconds from the recording's start; the +`latency` skill covers them. + +**What a query costs on a large recording.** Two choices decide it, and neither changes the +result: + +- **Name the event type.** Only the event types a query names are decoded, so a query for + one rare type does not pay for decoding the common ones. +- **Put a lower bound on `startTime` in the root brackets.** `after(startTime, …)`, + `between(startTime, …)`, `on(startTime, …)`, `startTime>=N` and `startTime>N` let the + parser skip every chunk that ended before the bound. An upper bound alone + (`before(…)`, `startTime<=N`) skips nothing. Nor does a time condition inside a pipeline + `filter(…)`, or one joined to another field with `or` or `not` — combine with `and`. + ### Pipeline operators | Group | Operators | diff --git a/plugins/jafar-perf/skills/latency/SKILL.md b/plugins/jafar-perf/skills/latency/SKILL.md index a6bd616..55b318e 100644 --- a/plugins/jafar-perf/skills/latency/SKILL.md +++ b/plugins/jafar-perf/skills/latency/SKILL.md @@ -39,10 +39,37 @@ Each resource carries an `assessment`; `insights.bottlenecks[]` names the satura `queue_saturation` is the one most often missed: an executor whose queue depth grows means requests wait before any code runs for them. No amount of method optimisation fixes it. -Narrow the window when the recording spans a mix of load levels: +Narrow the window when the recording spans a mix of load levels. `jfr_use` and `jfr_tsa` +take the same two optional bounds: ``` jfr_use startTime= endTime= resources=threads +jfr_tsa startTime= endTime= correlateBlocking=true +``` + +`startTime` and `endTime` are nanoseconds from the recording's start. An epoch-nanosecond +timestamp — the `startTime` of an event, copied from a query result — is also accepted, so +the events that bracket a spike can be used as the bounds directly. The window selects +events by their start time. + +Confirm the window before reading the metrics. The result's `timeWindow` repeats +`startTime` and `endTime` as given and adds `recordingStartEpochNanos`, +`startTimeEpochNanos` and `endTimeEpochNanos`, which show how the bounds were interpreted. +Check that they cover the interval you meant, and quote them in the report. + +- A `timeWindow` without those three fields comes from a server that predates this contract. + It compares the bounds with epoch timestamps as given, so offsets from the recording's + start select nothing. Do not report such a result as windowed. +- If the recording's start cannot be read, the call fails rather than guessing. Report the + failure; do not substitute the whole-recording result. +- `jfr_tsa` answering with only a `message` that no execution samples fell in the window + means the window is empty, not that the threads were idle. + +To run a `jfr_query` over the same window, put the two epoch values in the root brackets +(see the `jfrpath` skill for why the lower bound belongs there): + +``` +jfr_query query="events/jdk.JavaMonitorEnter[startTime>= and startTime<=] | groupBy(monitorClass, agg=sum, value=duration) | top(10, by=value)" ``` ## 3. Which lock?