Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 32 additions & 1 deletion plugins/jafar-perf/skills/jfrpath/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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>=<epochNanos> 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 |
Expand Down
29 changes: 28 additions & 1 deletion plugins/jafar-perf/skills/latency/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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=<ns> endTime=<ns> resources=threads
jfr_tsa startTime=<ns> endTime=<ns> 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>=<startTimeEpochNanos> and startTime<=<endTimeEpochNanos>] | groupBy(monitorClass, agg=sum, value=duration) | top(10, by=value)"
```

## 3. Which lock?
Expand Down
Loading