Adds Debug > Trace Stream Chain: paused on a line with a java.util.stream chain, the program runs that chain once, for real, while every element is recorded at every step, and a Stream Trace tab shows it Flat (all steps side by side, an element followed through the chain) or Split. Nothing is evaluated twice; the editor stops right after the statement. - java/jvm-inspect 1.1.0 gets openidea.jvm.stream.*: wraps each step with peek(recorder) (a class defined in the debuggee), runs the terminal operation by invokeMethod, keeps breakpoints off while the chain runs and restores them, then parks the thread. The jar is reproducible from build.py (JDT LS 1.63.0, JDK 25). - New ide-streams crate finds the chains on the paused line (tree-sitter) and builds the plan; ide-dap drives continue, wait, step out, collect. IPC: debug_stream_chains, debug_stream_trace, debug_stream_trace_abort. - No automatic timeout: a long chain shows progress with Stop Recording and Abort Operation. At most 50,000 records are kept; banners say when values were dropped, a parallel chain ran sequentially, or breakpoints were off. Co-authored-by: ntbang0901 <121003585+ntbang0901@users.noreply.github.com>
18 KiB
JVM inspection inside java-debug
An OSGi bundle loaded into JDT LS next to microsoft java-debug. While a Java debug session is suspended, it lists the instances of a class, the fields of an object and the objects that refer to it, and counts the instances of every loaded class; it also traces a stream chain while the program runs it. It works on java-debug's own JDI connection to the debuggee, so no second debugger connects to the JVM.
Commands
Every command but openidea.jvm.vms takes target first:
{"pid": n|null, "host": s|null, "port": n|null, "generation": n}. A launch session is found by
pid (the process java-debug started); an attach session by the remote port of java-debug's socket,
then by host when several VMs share that port. Two JVMs running the same program have the same
thread ids and names, so threads are never used to tell sessions apart.
| Command | Arguments after target |
ok |
|---|---|---|
openidea.jvm.vms |
none (no target) |
[{pid, remoteHost, remotePort, localPort, version, canGetInstanceInfo, timeout}] |
openidea.jvm.classes |
none | [{name, instances}], classes with no instances left out |
openidea.jvm.instances |
className, limit |
[JvmValue], at most 1000 |
openidea.jvm.fields |
objectId |
[{name, value}]; the first 100 elements, as "[i]", of an array |
openidea.jvm.referrers |
objectId, limit |
[{value, via}], at most 200; via lists the fields or "[i]" slots |
A reply is {"ok": payload} or {"error": code, "detail": text}, code being one of
unsupported, vmNotFound, stale, collected, classNotLoaded, notSuspended, timedOut.
Anything else (a malformed argument, a JDI error the bundle does not expect) is an ordinary
executeCommand error. Values have the JSON shape of ide_jvm_inspect::JvmValue. JDT LS writes
replies with Gson, which leaves out null members: an attached VM has no pid, and a long string
no text.
- Data is read only while some thread of the VM is suspended (
notSuspendedotherwise), one command per VM at a time. - An
objectIdis valid only in thegeneration(the session's stop) it was returned in; any other isstale. Each VM keeps a table of the objects the bundle handed out, emptied when the generation changes or when it grows past 100 000 entries. - Previews follow the JDWP link's rules: arrays give only their length, boxed types the primitive in
their
valuefield, aStringthe length of its backing array (bycoder) and its text only up to 1000 characters. Nothing is invoked: notoString, noinvokeMethod. - A referrer array longer than 10 000 elements is not searched for the slot (
viais empty). - An object collected before its preview is left out of
instancesandreferrers.
Stream trace
The openidea.jvm.stream.* commands trace a stream chain while the program itself runs it, so no
lambda runs twice. They take target first, like the commands above, then one object:
| Command | Object after target |
ok |
|---|---|---|
stream.arm |
{threadId, plan, budget} |
{traceId} |
stream.wait |
{traceId, ms} |
{state, records, dropped, elapsedMs, detail?} |
stream.stop |
{traceId} |
{records} |
stream.abort |
{traceId} |
{state, holders?}, holders being [{threadId, name}] |
stream.collect |
{traceId} |
{records: [{step, value}], dropped, terminal, skippedBreakpoints, sequentialized} |
stream.release |
{traceId} |
{} |
plan is the JSON of ide_streams::RealRunPlan; budget, a whole number from 1 to 2³¹ − 1
(default 50 000), caps the records kept, past which they are only counted in dropped. wait's
state is running, parked, failed or cancelled (both with detail). abort's is interrupted, stopped or
stuck while the terminal runs, cancelled before it started and finished once the trace parked
or failed. collect takes the new stop's target.generation; a record's step counts the wrapped
ops from 0 (the source), modifiers left out, and value, like the terminal's, is a JvmValue
preview (a primitive result previews as primitive). terminal is {kind: "value", value},
{kind: "void"} or {kind: "threw", exception}.
Besides the codes above, a reply's error can be noSession (java-debug registered no session for
the VM), notAtChainStart, busy (the VM has a trace still running; collect before the trace
parked), noTrace (the traceId is not the VM's current trace), badArgument (a budget out of
range) or failed (collect on a failed trace, with its detail, or a JDI failure the commands do
not expect, or a VM unlike the plan). collect in the stop arm ran in is stale. Any other malformed argument is an
ordinary executeCommand error.
armneeds the thread suspended by an event (a breakpoint or a step) and a VM that can force early returns and report return values (HotSpot 11 to 25 can). It defines the recorder (recorder/OiRecorder.java, embedded asai/openidea/jvminspect/OiRecorder.bin) in aSecureClassLoaderof its own whose parent is the boot loader, once per VM, and creates the log and the exception that cancels the terminal (java.lang.RuntimeException: oi-cancel:<nonce>).- From
armuntil the trace is released, every enabled breakpoint, exception, method entry, method exit and watchpoint request that is not the bundle's own is switched off, then back on: java-debug makes a function breakpoint a method entry request and a data breakpoint a watchpoint request. A breakpoint hit while the bundle invokes into the thread hangs the session. A request java-debug deleted meanwhile (the user edited or removed the breakpoint) stays off: Eclipse JDI would enable a deleted request again, so only requests the VM still lists are switched back on. - One trace per VM. A finished trace (parked or failed) is released by the next
armon that VM or when the VM disconnects; the client need not callrelease. Releasing a parked trace the client never stepped out of resumes the thread; releasing one whose terminal still runs takes effect when the terminal returns, and until then the VM's nextarmisbusy. The program then runs on with the terminal's outcome and the trace isfailed(released), so a laterabortisfinishedand the nextarmreplaces it. After the VM disconnected,waitstill answers the trace's last state and the counts last read, for the 16 latest such traces. armrefuses a chain that has started (notAtChainStart): the stop must be on or after the statement's first line with no code of those lines before it. javac puts a statement's first instruction on its first line; ECJ, which JDT LS builds with, gives a head likeList<String> out =no code, and a head liken =only the store after the chain. A stop inside a lambda (a synthetic method, or one namedlambda$…) is refused when a deeper frame of the same class has code on the chain's lines up to the stop: that frame runs the chain, and the stop is in one of the chain's lambdas, from which the root is never called. A chain written inside a lambda body has its lines in the lambda alone and stays traceable. Alocalroot must be declared as aStream,IntStream,LongStreamorDoubleStream(unsupportedotherwise);armreplaces it bylocal.peek(recorder).- After the client continues the thread, each build-phase
MethodExitof the chain's next op is held and its stream returned asstream.peek(recorder)throughforceEarlyReturn. The root is matched by name, JVM arity, stream return type and caller (the stopped method, one frame deeper), after the plan'sskipsuch exits; every later op by receiver: a call from that method on the last wrapped stream is the chain's next op, and one that differs from the plan fails the trace (missed <op>) and lets the program run on. Modifiers are matched but not wrapped. Withsequentialize, the source becomespeek(…).sequential()and eachparallel()returnssequential(). - The build phase ends in
failed(the chain did not run: …), the program running on, when the statement throws before the terminal is called (the root's or a step's arguments). The bundle also watches the stopped method's class for method exits, and steps out of its frame: JDWP reports no method exit for a frame an exception pops, but the step out lands in the caller's handler. Any of the trace's events with that frame gone, or on a line outside the plan'sfirstLine..lastLine(the statement caught the exception), fails the trace. A breakpoint on the line the step out lands on is missed (it is switched back on only once the thread is there), and so are breakpoints the frame's own catch block passes before the trace's next event. - At the terminal's
MethodEntry, with no method request left on (any slows the thread to the interpreter), the bundle runs the terminal once byinvokeMethod, with the JDI timeout raised, and forces its result as the entered frame's return, or throws its exception there. The thread stays suspended (parked) until the client's DAPstepOut. Breakpoints java-debug created sincearmare silenced too, right before the invoke, and again at each 500 ms check of awaitwhile it runs; all are switched back on when it returns. A breakpoint added between two checks can still be hit inside the invoke: java-debug reports the stop, and a DAPcontinueof the thread lets the invoke go on (ide-dap does that unseen while the trace runs). The outcome is forced into the frame before it is pinned, so the pending return keeps it reachable; should it be collected before that, the program gets the cancel exception and the trace fails. waitreturns as soon as the trace leavesrunning, or afterms, at most 30 000. While the terminal runs it also checks every 500 ms whether the VM began to shut down (jdk.internal.misc.VM.initLevel):System.exitin a lambda makes the VM wait forever to report its death while the bundle's invoke runs, so no disconnect comes. The trace then fails, with the breakpoints back on; the debug session has to be stopped.stoplowers the log's budget to the records so far by a field write: the program keeps running untouched.abortinterrupts the thread, waits 2 s for the terminal to return, then throws the cancel exception into it, waits 2 s more, and else lists the suspended threads that own a monitor. JDWP holds an interrupt or stop of a thread handling an event until that event's handler exits, and the invoke runs inside the handler of the terminal's entry; any event of the thread inside the invoke lifts the hold. So the bundle adds a method entry request on the thread, counted once and suspending nothing, right before the invoke: it fires on the terminal's own entry. Without it only a class first prepared inside the invoke lifted the hold, and a VM that had run those stream classes before (an earlier stream or trace) answeredstuck. Before the terminal started, either takes the trace down (cancelled,cancelled before the terminal ran) and the program runs on untouched.collectreads the log 16 384 elements per JDWP request and previews every value into the handle table of the inspect commands, so the UI can expand them; the log keeps them alive until the trace is released.skippedBreakpointscounts the line, function and data breakpoint requests silenced (exception breakpoints left out: JDI cannot tell whether a silenced request would have been hit).- Timing, the 1M-element chain of
tests/stream.py(real_run_d_million, Apple M4 Pro, JDT LS 1.63): 78–138 ms from DAPcontinuetoparkedon JDK 11, 17, 21, 23 and 25; DAPstepOutpluscollectof its 50 000 records 4.4–4.7 s.
classes and referrers can take seconds on a large heap. Eclipse JDI fails a request after
getRequestTimeout() (3000 ms by default), and the timeout is per VM: java-debug's own requests
waiting behind the command time out too. These two commands raise it to at least 60 000 ms and,
when done, put back the old value unless something else changed it meanwhile (java-debug applies its
timeout setting to every VM when it changes).
Internals it depends on
java-debug is not pinned: the app installs the latest vscode-java-debug. The bundle reaches the VMs through these non-API members, by reflection:
com.microsoft.java.debug.plugin.internal.JdtVirtualMachineManagerProvider#getVirtualMachineManager()AdvancedVirtualMachineManager.connectedVMs(a synchronized list)org.eclipse.jdi.internal.VirtualMachineImpl#packetReceiveManager()org.eclipse.jdi.internal.connect.PacketManager.fConnectionorg.eclipse.jdi.internal.connect.SocketConnection.fSocket
The stream commands reach java-debug's debug session of a VM, and its events, through:
org.eclipse.core.internal.resources.Workspace.notificationManager→NotificationManager.listeners→ResourceChangeListenerList.listeners(aCopyOnWriteArrayList) →ListenerEntry.listenercom.microsoft.java.debug.plugin.internal.JavaHotCodeReplaceProvider.currentDebugSession, a listener registered by each session whosehotCodeReplacesetting is notnever(the app setsauto)IDebugSession#getVM(),#getEventHub(),IEventHub#events()and RxJava 2'sObservable#subscribe(Consumer, Consumer)/Disposable#dispose(), loaded from the java-debug bundleDebugEvent.event,.eventSetand.shouldResume: set tofalsein the listener, it keeps the event's thread suspended, as java-debug does for conditional breakpoints
and, in the debuggee, jdk.internal.misc.VM.initLevel and .SYSTEM_SHUTDOWN (JDK 9 to 25), read as
static fields to see the VM shutting down while the terminal runs; without them that check is off
and, as API of org.eclipse.jdt.debug, org.eclipse.jdi.VirtualMachine#getRequestTimeout /
#setRequestTimeout and org.eclipse.jdi.TimeoutException. When any of these is missing or
changes shape, every command answers unsupported; nothing throws into java-debug.
Checked with JDT LS 1.63.0.202610191322 (org.eclipse.jdt.debug 3.27.0) and java-debug plugin
0.53.2 (vscode-java-debug 0.60.0).
Rebuild
Build dependency: JDT LS 1.63.0 build 202610191322,
the same as java/java-usages. Check the extracted distribution from its root
(sha256sum -c /path/to/build-dependencies.sha256), then with Java 25 on PATH:
python3 build.py /path/to/jdtls # writes openidea-jvm-inspect.jar
python3 build.py /path/to/jdtls --out x.jar # writes x.jar instead
python3 build.py /path/to/jdtls --test # compiles tests/SelfTest.java with the sources and runs it
The build uses the distribution's ECJ and plugin jars plus the jdimodel.jar nested in
plugins/org.eclipse.jdt.debug_*.jar, sorted inputs and fixed zip timestamps; bytecode targets
Java 21. The recorder is compiled by the javac on PATH with --release 8, since the debuggee may
run Java 8. Build twice and compare: two builds of the checked-in jar gave
22980a16bd8e303d67ed2e04d76d8974f2d3981120c26e6d9afa47ba361b1503 openidea-jvm-inspect.jar
Change Bundle-Version whenever the jar changes: OSGi caches bundles by version.
Real JDT LS check
tests/inspect.py starts JDT LS with java-debug and this jar, debugs a small Heap program (a launch
and two attaches to the same program) and prints OK/FAIL/SKIP per check:
PATH=/path/to/jdk25/bin:$PATH \
OPENIDEA_TEST_JAVA=/path/to/jdk11/bin/java:/path/to/jdk21/bin/java \
python3 -I tests/inspect.py /path/to/jdtls /path/to/com.microsoft.java.debug.plugin-0.53.2.jar --heap 10000000
OPENIDEA_TEST_JAVA lists debuggee JDKs (:-separated; ; on Windows). The attaches use the
first; classes is checked on the JDK 11 one. With --heap N, a JDK 21 JVM holds N objects and a
DAP evaluate sent 0.5 s after classes starts must succeed, with the timeout back to 3000 after.
It stops every process it started.
tests/stream.py does the same for the stream commands, once per JDK in OPENIDEA_TEST_JAVA, with
a launch and an attach; both scripts share tests/jdtls_harness.py. The real_run_* cases trace
chains end to end (arm, DAP continue, wait, DAP stepOut, collect); one debuggee is compiled
with the distribution's ECJ, as JDT LS builds a project. --bundle takes a jar built with --out (default: the checked-in one) and
--case NAME runs only the cases whose name contains NAME:
PATH=/path/to/jdk25/bin:$PATH \
OPENIDEA_TEST_JAVA=/path/to/jdk11/bin/java:/path/to/jdk21/bin/java \
python3 -I tests/stream.py /path/to/jdtls /path/to/com.microsoft.java.debug.plugin-0.53.2.jar --bundle x.jar