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?