Skip to content

docs(jafar-perf): describe the fixed jfr_use/jfr_tsa time window and time-filter cost - #21

Merged
jbachorik merged 1 commit into
mainfrom
claude/jafar-perf-mcp-update-34fb51
Nov 15, 2026
Merged

jbachorik merged 1 commit into
mainfrom
claude/jafar-perf-mcp-update-34fb51

Conversation

@jbachorik

@jbachorik jbachorik commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

What & why

btraceio/jafar#206 made the startTime/endTime window of jfr_use and jfr_tsa work and stated its contract. It also made JfrPath queries cheaper in two cases. This brings the jafar-perf skills in line.

  • latency skill
    • Before: the only window text was jfr_use startTime=<ns> endTime=<ns> resources=threads. It did not say what <ns> is measured from, that jfr_tsa takes the same bounds, or how to read the result.
    • Now: it gives the contract (nanoseconds from the recording's start; an epoch-nanosecond timestamp is also accepted). It tells the agent to confirm the window from recordingStartEpochNanos, startTimeEpochNanos and endTimeEpochNanos in the result's timeWindow. It also shows how to run a jfr_query over the same window.
  • jfrpath skill
    • Before: before, after and on were named with no signature or example.
    • Now: a "Time filters" subsection shows them and says what makes a query cheap on a large recording: name the event type, and put a lower bound on startTime in the root brackets.

No skill or agent text depended on the old broken window, so nothing was removed. No tool or parameter was renamed, so allowlists are unchanged.

How verified

Gate Command Result
Tool references, pinned node scripts/check-tool-references.js --pinned OK: all 37 referenced tools exist (jafar-mcp 0.29.0)
Tool references, latest release node scripts/check-tool-references.js OK: all 37 (latest release is still 0.29.0)
Tool references, jafar main node scripts/check-tool-references.js --jar <shadow jar built from 724d2d28> OK: all 37
Repository validation scripts/validate-marketplace.sh Marketplace validation passed (13 eval cases, 5 plugins, 31 skills)
Window behaviour, main build stdio probe on jafar's test-ap.jfr, window 20 s–40 s jfr_tsa returns 4296 samples for offset bounds and for epoch bounds, equal to the jfr_query count for that window; timeWindow carries the three new fields
Window behaviour, pinned 0.29.0 same probe offset bounds return "No execution samples in time window"; epoch bounds return 4296; timeWindow has no new fields

Coverage notes

The tool-reference check catches renamed or removed tools, not changed parameters. The parameter contract was checked by reading the schemas and resolveTimeWindow on jafar main and by the probe above.

Not verified / known limitations

  • The pin predates the fix. The plugins pin io.btrace:jfr-mcp:0.29.0, and no release contains 724d2d28 yet. Until the pin moves, offsets from the recording's start select nothing on installed servers. The latency skill says how to recognise such a result (a timeWindow without the three new fields); that sentence can go once the pin moves.
  • NOT VERIFIED: the chunk-skipping and type-decoding speedups, and the multi-chunk exactness from shell-core: make JfrPath event-stream consumers safe for parallel chunk parsing jafar#204 | the test recording has one chunk; timing a large multi-chunk recording on both servers would verify them. The skill text follows doc/cli/JFRPath.md on jafar main.
  • NOT VERIFIED: the "call fails if the recording's start cannot be read" path | taken from the source; it needs a recording with unreadable chunk headers.
  • NOT VERIFIED: agent behaviour with the new text | the LLM evals are manual-only and were not run.
  • CHANGELOG.md is not updated.

Breaking changes / migration

None.

Links

🤖 Generated with Claude Code

…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 <ns> 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 <noreply@anthropic.com>
@jbachorik
jbachorik marked this pull request as ready for review November 15, 2026 17:49
@jbachorik
jbachorik added this pull request to the merge queue Nov 15, 2026
Merged via the queue into main with commit bbd127e Nov 15, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant