jvmlens

Turn JVM runtime evidence into a compact, LLM-ready diagnosis.

Profiling a JVM is well-served for humans — async-profiler, JFR, and the commercial GUIs all produce flamegraphs and recordings. None of those formats are built for an LLM to reason over: a jfr print dump of a short recording is hundreds of thousands of tokens and routinely overflows a model’s context window. jvmlens reads a JFR recording and emits a few hundred tokens of ranked, source-attributed signal you can hand straight to a coding agent.

Why

A 20-second profile-settings recording of a hot loop dumps roughly 380K tokens of raw jfr print — too big to paste. jvmlens turns the same recording into a ~400-token summary that names the hot application method, the leaking allocation site, or the contended lock. For an LLM, the summary isn’t just cheaper — for non-trivial recordings it’s the only input that fits.

What it does

Area Capability

Area	Capability
Inputs	An existing `.jfr` or a JMH `-prof jfr` directory (`analyze`, forks merged), a live JVM (`profile <pid>`, JFR or async-profiler), a warm-loop of any `main` (`bench`, no JMH module needed), a continuous ring buffer (`watch`, periodic or dump-on-trigger), or an in-process `-javaagent` (container-native).
Dimensions	CPU hot paths/leaves, memory + GC, lock contention, external I/O, virtual-thread pinning, deadlocks, and — via the agent — SQL, HTTP endpoints, messaging (Kafka / JMS / RabbitMQ), cache, MongoDB, Redis, and Micrometer timers, plus variable snapshots and a cross-dimension correlation that confirms an endpoint→query→GC chain when the captured call-path proves it. Each agent dimension is source-anchored (`· at Repo:88`) and feeds `--hints` (N+1 → batch, low hit rate, …).
Optimize loop	`analyze --baseline` diffs two runs (absolute-anchored), `--assert` gates a regression in CI (non-zero exit), `--hints` gives hedged fix directions, and `--top-k` / `--max-tokens` budget the size. A JMH profiler (`-prof …JvmlensProfiler`) prints the summary inline after a benchmark.
Outputs	Markdown / JSON / LLM-prompt; report focuses per dimension; scoped, navigable MCP tools (`jvmlens mcp`). Serves data only — no LLM egress.
Long-running	The agent’s `history=` appends a JSONL time-series; `jvmlens trend` reduces a multi-day run to a change-over-time digest.
Live control	Steer a running agent in-flight (start/stop, enable/disable dimensions, sampling density, filtering, top-N) via a watched control file + the `jvmlens control` CLI — no ports, no JMX.
Trust	Per-row hit counts and source-line anchors (`Svc.compute:88`), `[sampled]` vs `[measured]` tags, low-sample `⚠` caveats (CPU and per-site allocation), and an under-interpreting heuristic.

Inputs

An existing .jfr or a JMH -prof jfr directory (analyze, forks merged), a live JVM (profile <pid>, JFR or async-profiler), a warm-loop of any main (bench, no JMH module needed), a continuous ring buffer (watch, periodic or dump-on-trigger), or an in-process -javaagent (container-native).

Dimensions

CPU hot paths/leaves, memory + GC, lock contention, external I/O, virtual-thread pinning, deadlocks, and — via the agent — SQL, HTTP endpoints, messaging (Kafka / JMS / RabbitMQ), cache, MongoDB, Redis, and Micrometer timers, plus variable snapshots and a cross-dimension correlation that confirms an endpoint→query→GC chain when the captured call-path proves it. Each agent dimension is source-anchored (· at Repo:88) and feeds --hints (N+1 → batch, low hit rate, …).

Optimize loop

analyze --baseline diffs two runs (absolute-anchored), --assert gates a regression in CI (non-zero exit), --hints gives hedged fix directions, and --top-k / --max-tokens budget the size. A JMH profiler (-prof …JvmlensProfiler) prints the summary inline after a benchmark.

Outputs

Markdown / JSON / LLM-prompt; report focuses per dimension; scoped, navigable MCP tools (jvmlens mcp). Serves data only — no LLM egress.

Long-running

The agent’s history= appends a JSONL time-series; jvmlens trend reduces a multi-day run to a change-over-time digest.

Live control

Steer a running agent in-flight (start/stop, enable/disable dimensions, sampling density, filtering, top-N) via a watched control file + the jvmlens control CLI — no ports, no JMX.

Trust

Per-row hit counts and source-line anchors (Svc.compute:88), [sampled] vs [measured] tags, low-sample ⚠ caveats (CPU and per-site allocation), and an under-interpreting heuristic.

See Installation, Usage for the full reference, and Integrating to profile another project.