Usage

The agent optimize→measure loop — "did the fix work, what changed" — is a single flag. -b / --baseline diffs <file.jfr> (the after) against a baseline (the before) and names what moved, instead of making you eyeball two summaries:

It diffs the totals (incl. total allocation bytes — the absolute memory anchor), hot paths, allocation sites, locks, and every extended section. Each row is anchored on its absolute weight (bytes / ms / samples) with the direction (▲/▼) and the share change as secondary context, ranked by the size of the absolute change; NEW / GONE are called out, and rows that barely moved drop. Anchoring on absolute matters: in an optimize loop the total shrinks, so a site whose absolute bytes fell can show a rising share — share alone would mislabel a real win as a regression. -a/-x scoping applies to both recordings.

Optimizing a JVM library is almost always a JMH loop, and JMH’s -prof jfr writes one .jfr per fork (often all named profile.jfr in per-benchmark subdirs). Point analyze (and --baseline) at a directory and jvmlens finds every .jfr under it and merges the forks into one summary, so the signal isn’t split:

(JMH records the whole fork including warm-up; for measurement-only signal, configure JMH to delay the recording past warm-up, compare steady-state runs, or pass --skip-warmup <ms> to analyze — it drops the first <ms> of each recording, measured per file from that file’s earliest event, so each fork’s own warm-up is trimmed and hot paths reflect steady state.)

Or skip the separate step entirely with the JMH profiler plugin — it records the fork and prints the summary inline when the trial ends. Put jvmlens-jmh.jar (a tiny engine+profiler jar, no Spring/picocli/jmh) on the benchmark’s classpath and:

appPackage (+-separate several) scopes to your code; report focuses the summary. An unknown option key is a hard error with a did-you-mean (no silent misconfiguration). The plugin runs in JMH’s host process and reuses the same engine as analyze.

For a before→after diff entirely inside JMH — no separate analyze — keep the fork’s recording with keep=<path> (so it can seed the next run’s baseline) and diff against a prior one with baseline=<prev.jfr> (the profiler prints the change report instead of the summary):

--hints appends a hedged ## Likely fix directions [possible] section that maps recognized hot-frame / allocation shapes to a one-line direction, each grounded in the row that triggered it — e.g. DoubleToDecimal/formatUnsignedInt → "number→string formatting", a LinkedList$ListItr.<init> self-time → "per-iteration iterator allocation", AbstractStringBuilder.ensureCapacity → "presize the buffer". It is off by default (the report stays clean data) and every line is tagged [possible] — a direction to investigate, never an assertion.

--top-k <n> keeps only the top n rows per section; --max-tokens <n> shrinks top-k until the summary fits roughly n tokens (chars/4). For an always-on agent that adjusts limits at runtime, the agent control plane’s topn does the same per-dimension (see Runtime control).

By default every interval is emitted. Pass any threshold and watch instead stays quiet and emits only when a window breaches it — the production "dump-on-trigger" mode:

Like a desktop profiler’s live controls, the agent can be steered at runtime — without a restart — through a control file it watches (control=<file>). No ports, no JMX: an operator appends commands over whatever access they already have, via the jvmlens control CLI (run it on the host: kubectl exec, ssh, …):

Commands: start / stop, clear (reset the window + stores), dump (emit now), enable <dim> / disable <dim> (db/web/messaging/cache/micrometer/snapshot/deadlock), settings <profile|default> (sampling density), interval <seconds>, scope app|exclude <prefix> / scope reset (filtering), topn [<category>] <n> / topn reset (rows per section — category is cpu/perf, memory/mem, locks, io, pinning, or a plugin like db/web), and status. Each command makes the agent publish its state to <control-file>.status, which the CLI reads back and prints — so topn db 5 returns the resulting limits to you.

Launching paused and then start after warm-up is the clean fix for short cold runs profiling startup rather than the workload — no more guessing a --warmup duration.

out is overwritten each interval — only the latest window survives. For a multi-day watch, add history=<file.jsonl> and the agent instead appends one compact sample per interval (covering all three dimensions — CPU, memory, wait), so nothing is lost:

Let it run, then trend reduces the accumulated run to a change-over-time report — what moved across the days, not a single snapshot:

The digest reports each dimension’s first-third→last-third direction (rising / flat / falling), whether the hot path stayed stable or shifted, when lock contention appeared, and a hedged retention indicator — old-object growth alongside rising GC pressure is flagged as possible retention growth, never a confident "leak".

Add db to the agent options and it instruments java.sql.Statement.execute* (ByteBuddy) to time JDBC calls, aggregating them by sanitized SQL shape (literals parameterized, so no values reach the summary) into a Top SQL (by total time) section — each shape with its call count, average latency, and a hedged possible N+1 flag for high-count low-latency shapes:

The SQL comes from the statement argument (plain Statement) or the statement’s toString() (most PreparedStatement drivers — H2, PostgreSQL); unknown shapes degrade to ?. This is profiling signal, not a query log — it never records literal values.

Add web and the agent instruments HttpServlet.service (ByteBuddy; both jakarta.servlet and javax.servlet, read reflectively so jvmlens needs no servlet dependency — Spring MVC’s DispatcherServlet is covered by this one point). Requests aggregate by route shape (numeric / UUID / long-token path segments become {}, query strings dropped) into a Top HTTP endpoints (by total time) section, each with request count, average latency, and an error count (status ≥ 400):

Beyond performance, the agent can answer correctness questions — what values flow through a method — without stopping the app. Add snapshot=Class#method (semicolon-separate several) and the agent instruments those methods and appends a Variable snapshots section to the summary: per call site, the call count and a per-argument digest (distinct values, null rate, numeric range):

Method arguments need no debug info; capturing locals (requires -g) and conditions/PII redaction are planned.