Java Agent

Snippet ids are stable: curl-download, maven-download, gradle-kotlin-download, gradle-groovy-download, maven-plugin, gradle-kotlin, gradle-groovy, quarkus-dev, surefire, intellij, and java-tool-options.

If the application's JVM has -Dmaven.repo.local=..., that repository is honored. When the application knows its local repository, the download command includes -Dmaven.repo.local=<absolute path>, so the jar and the setup card's path stay aligned.

• threads installs and self-tests on, and restores java.lang.Thread off.
• files and environment stop recording at once, then reinstall the transformer that processes, network, and blocking share and self-test them again; one whose core hook fails stays off for the JVM's life. Runtime Insights' run comparison leaves the compared sensors out of a run in which one of these was switched.
• thread-activity and security-sinks have a transformer of their own. thread-locals transforms nothing.
• security-sinks switches its JDK checks and request-value matching together, but never turns matching on by itself; switching it off wipes the values held for running requests.
• Another sensor id or a body without enabled answers 400. A 409 means the agent is not attached or not armed, an older agent predates switches, the claim changed meanwhile, or the sensor already failed its self-test in this JVM.

• Classes loaded before the claim are instrumented when the sensors install and marked late for that run.
• The first claim in a JVM installs the sensors off the claiming thread; a DevTools restart finds them installed.
• A SpringApplication run inside another one's, such as Spring Cloud's bootstrap context, neither claims nor releases.
• Sensor removal runs off the caller's thread. A new claim supersedes a queued release. If restoring the application classes fails, the affected sensors stay disabled in that JVM.
• A sensor row's This claim column says whether the armed claim uses an installed transformer; a sensor missing from bootui.agent.sensors reads inactive.
• The engine looks up the bridge only from the bootstrap class loader, so an application-classpath copy is ignored.

The panel shows per hook whether the type exists, whether it was instrumented, its self-test result (passed, failed, not-exercised, unsupported, or not-run), and how many tasks it received or ran. A failed or inconclusive self-test of a ThreadPoolExecutor or ForkJoinTask.doExec hook disables propagation for that claim; the next claim tests again. A failed AsyncSupply or AsyncRun hook disables nothing: the pool's run hook propagates that stage without reading its outcome. Hooks are verified on JDK 17, 21, 25, 26, and 27; on any other JDK the report warns that the self-test decides.

Nothing is opened when the worker already works for that request, for BootUI's own work, on bootui- threads, or when no request or execution owns the work. Propagated work is not metered as its request's own CPU time and allocation.

A task is after the response when its body ends after its request's response started. A normal JDK body whose handler waited for its result ended before it. A request that marked no response is compared with its end; on WebFlux, which marks no request phases, the request's end stands in for the response.

For a body that ended before the response, the badge and the request profile still mark the task when its tail ran SQL, a REST call, or a message at least 2 ms past the response, failed after it, or ran at least 50 ms past it. Runtime Insights' work-after-response reports only I/O or failures after the response, so a task badged for computation alone is not an insight. These observations apply only while the agent is armed, the executors sensor passed its core-hook self-test, and BootUI attached its handoffs to the claim; otherwise the panel says which is missing.

Once the executors sensor has counted overflow, the panel warns that a shared task object may have run with another request's context.

• Parallel-stream subtasks run by other workers stay unowned.
• Pools whose workers started before the first claim never apply their tasks.
• A task submitted when the bridge holds 32,768 entries runs unowned, and entries of earlier claims count until they run or are released.
• A task submitted before a DevTools restart or a Quarkus live reload that ends after it is never reopened.
• A task object pending across claim generations stays ambiguous and unowned until its pending count drains.
• One window, bootui.agent.executors.max-handoff (5 minutes), bounds a handoff: later work is not attributed to the request, and a task that ends later is published capped.

A thread is propagated only when application code starts it: the first caller of start() outside the JDK must belong to the claimed packages. Threads started by a library or framework, pool workers, and a Thread subclass whose run() is outside the claimed packages (such as java.util.Timer's) never inherit the request. A background thread the application starts lazily from a request carries that request until it ends, bounded by the handoff window. Its counters are those of the executors sensor, plus Library threads skipped and Pool workers skipped.

On JDK 21 and later the task's call inside Thread.runWith is replaced, never wrapped, so scoped-value bindings that a StructuredTaskScope subtask inherits stay visible.

Each instrumented method gets one entry check. Its first call in a run marks it executed and, when a request or another BootUI execution owns the call, records the request id, route, and time. Each claim starts a new run, so a DevTools restart or Quarkus live reload counts afresh. A second transformer, which never changes a class, counts the classes each code source loads in this run, with the route that loaded the first one.

Never instrumented: static initializers, $-prefixed methods, abstract and native methods, BootUI's own classes, the agent, proxies (Spring CGLIB and AOT, ArC, Hibernate, Mockito), synthetic classes, and classes loaded from a test root. A method counts as tracked only once its class was transformed. A class instrumented only after it loaded may have run before, unseen: its methods are marked late for that run.

Accepted limits: calls made before BootUI claims the agent are not seen, a method HotSwapped without a restart keeps its flag, and Mockito's inline mock maker dispatches a stubbed call before the sensor's check. The sensor shares its transformer with the code-paths sensor.

• Records travel through a bounded ring of bootui.agent.ring-capacity records (65,536 by default) that never blocks. A dropped record loses only the first request, route, and time, never the fact that the method ran.
• At most 262,144 methods and 4,096 code sources are tracked for the agent's lifetime.
• Each claim admits its context class loader and ancestors, so old objects from earlier runs cannot mark a changed method executed. An application claiming with an unrelated or null context loader must supply the application loader as its thread context loader.
• For the Vulnerabilities panel's runtime reach, each jar keeps a bounded set of hashes of the class names it defined.
• Hooks: method entry (every non-abstract, non-native method and constructor of the claimed packages) and class load. The report carries the counters as methodsTracked, executedThisRun, methodOverflow, transformFailures, codeSources, ringDropped, ringLost, and internOverflow. Missing tracking evidence is unknown, never confidently never executed.

The bean classes come from the adapter: on Spring, the user class of every bean in the application's packages; on Quarkus, classes with a bean-defining annotation, @Path, or @Provider. Never timed: constructors, static initializers, static and private methods, synthetic and bridge methods, equals, hashCode, toString, record accessors, interfaces, lambdas, and everything the inventory sensor never instruments. A framework or library method appears only as time of the bean method that called it.

A method called more than 50,000 times a second with a mean under 2 µs, such as a getter in a loop, is no longer timed for the rest of the run, and its time stays in its caller. After 100 internal errors the sensor switches itself off for the JVM's life.

Accepted limits: Spring WebFlux and reactive Quarkus endpoints time the assembly of their pipeline on the thread that builds it, not its execution, so these trees do not split the handler phase. Calls made before BootUI claims the agent are not seen.

• inventory and code-paths share one transformer with one advice and self-test each. A failed self-test removes only that sensor's advice.
• A request's tree is handed to BootUI as one fragment of at most 512 nodes; calls deeper than 32 levels stay in their ancestor's time, and past 480 nodes each caller's further methods share one Other node.
• Nothing on the application thread blocks or allocates per call: an empty pool or a full queue (4 MB) drops the fragment and counts it. BootUI's drain thread reads fragments every 100 ms and a request tree settles about two seconds later.
• The report carries the counters as fragmentsFlushed, fragmentsDropped, queueDropped, callsDropped, queueBytes, excludedMethods, and errors, with disabledReason when the sensor stopped. The hook is bean methods.
• The agent's bridge carries no line numbers, so stepping into an instrumented method in a debugger steps over the advice. A debugger stepping into BootUI's correlation capture can stop there, unless io.github.jdubois.bootui.* is in its step filters.

• The self-test starts a deliberately invalid command that the JDK rejects before spawning anything. A failed self-test disables the sensor.
• Completion is watched with Process.onExit(), for at most 1,024 processes at once.
• BootUI's own process starts and bootui- threads are ignored.
• A start names its owner: a request, an execution no request owns (a scheduled run, a consumed message, a WebSocket message), or neither.
• All side-effect sensors share a ring of 1,024 records and a string table of 8,192 strings a run. A full ring drops and counts records instead of blocking. After 100 internal errors a sensor switches off for the JVM's life.
• The sensor's coverage reads recording when this application's claim includes it, otherwise not-claimed, not-available, or failed with the reason.

A target is the remote's host string and port, never resolved, with anything up to an @ dropped. At most 1,024 distinct targets are kept per run; the others share (other hosts). BootUI's own work is never recorded. Loopback connections to databases, brokers, and containers are.

A connection or datagram is not captured by any panel when no visible panel shows its work. JDBC, messaging, and mail connections are captured by SQL Trace, the broker's panel, or Email. Any other connection is captured by REST Client Trace when a call of the same request names its host and port. Infrastructure clients (OpenTelemetry and Zipkin exporters, metrics registries, DNS, Testcontainers, DevTools) are marked infrastructure. get_side_effects with query not captured lists the uncaptured rows.

Known limits: asynchronous socket channels, connected datagram writes, and native code are not seen, and a lookup the JVM's cache answered is not counted.

• A hook that fails its self-test is left out and listed under hooksLeftOut; a failing core hook disables only this sensor.
• The client is recognized from frames and thread families, then from a configured exporter endpoint, then from a well-known port. A REST client call is matched to a connection within a few seconds.
• The runtime model gains observed OPENS edges from routes and jobs to HOST nodes keyed host:port.

The agent turns a path into a pattern before anything leaves the hook, so a raw path and the user name in it never reach BootUI. The working directory becomes ., the temporary directory $TMPDIR, and the home ~. Tokens, UUIDs, hex and alphanumeric ids, and digit runs become {token}, {uuid}, {hex}, {id}, and {n}, so report-2026-10-05.csv in target/reports is ./target/reports/report-{n}-{n}-{n}.csv. The engine also masks segments its secret detector recognizes.

Class files, jars, and files a class loader reads are counted in buckets, never recorded per route. Rows carry where they came from (application, library, logging, class path, or JDK).

• File.delete, File.renameTo, File.createNewFile, AsynchronousFileChannel, memory-mapped access, and native code are not seen.
• One operation records once. A generation keeps at most 3,000 distinct path patterns; beyond that the target is (too many distinct paths).

Each match is a row of the Side Effects Security sinks tab and of get_side_effects' security-sinks query, worded as a fact, never as a vulnerability. A row names the sink, the parameter's name, the call site, and the sink's text with the value redacted to {name}. It never holds the value.

Form values, headers, and bodies are never held. The values live in memory only while a request runs, are removed when its response completes, and are wiped on a new claim, a restart, a release, or when the sensor is switched off. They are never persisted, logged, or displayed.

• The holder keeps at most 128 requests and 32 values of 4 to 256 characters each. A missed end is swept after 60 seconds.
• Matching is bounded per request. After the budget, later sinks are not checked and a files or processes row says (not kept: not checked for request input).
• A value that is a number, true/false, or outside an SQL literal may be a word the text always holds. Such a match is shown only once a second request produced a different raw text with the same redacted text.
• A JDK HttpClient call is checked only when it goes through a REST client BootUI records.
• Clear recording clears the rows.

With security-sinks in bootui.agent.sensors, whatever request-values says, the sensor also hooks the JDK's security APIs and records three kinds of facts as Security sinks rows, each worded as what was seen:

A caller inside the JDK asking for SHA-1 or MD5 itself is the JDK's own use, counted and never shown. A group whose core hook fails is switched off alone.

Library trust managers that accept every certificate are recognized by exact class name: Netty's InsecureTrustManagerFactory, Vert.x's TrustAllTrustManager, and Apache HttpClient's TrustAllStrategy and TrustSelfSignedStrategy. Not detected: any other library's trust-all and Netty's OpenSSL provider.

Not checked: KeyGenerator, Signature, Mac, SecureRandom, PBE algorithms, and a library's own default verifier or factory. Without jdk.unsupported, the deserialization group is off.

Event loops are Reactor Netty's on Spring WebFlux (and on a WebClient's loops in Spring MVC) and Vert.x's on Quarkus. On a servlet container the tab is not-applicable. Reactor's parallel, single, and boundedElastic schedulers, Vert.x workers, and virtual threads are never event loops. A park shorter than 1 ms is only counted.

Thread.sleep and Object.wait are native, so the agent rewrites their call sites in the application's classes into calls that call the original and record around it. A stack trace through a rewritten call shows one extra frame, io.github.jdubois.bootui.agent.bridge.Blocking.sleep or waitOn; exceptions and the interrupt flag are unchanged. The sensor does not see a library's own sleep, Thread.join, or blocking on a loop before its first request.

A row's origin is application, library, or jdk. A thread still alive, or an executor not shut down, 250 ms after the response completed is reported once as left running. Threads and executors are tracked weakly, so the sensor never keeps them alive.

• Hooks: Thread.start and VirtualThread.start (starts), ThreadPoolExecutor.<init>, ForkJoinPool.<init>, and ThreadPerTaskExecutor.<init> (creations), and their shutdown methods. The common pool is never recorded.
• At most 1,024 threads and 1,024 executors are tracked. Beans created as singletons are never tracked.
• It does not see threads created through classes that bypass the JDK's, such as Netty's own thread-per-task executor.
• A core hook that fails its self-test disables the sensor alone; JDK 21 hooks are unsupported on JDK 17.

A row's target is the static field that holds the thread local, such as com.example.TenantContext.CURRENT. Frameworks that set and clear their own thread locals (Spring's request and transaction holders, MDCs, Micrometer, OpenTelemetry, Jackson, Netty) are dropped and counted. Event loops, virtual threads, and scopes no request or job owns are not scanned. Add thread-locals to bootui.agent.sensors, or switch it on at run time.

A scope opens around a Spring MVC request, a request's task on a pool worker, Spring WebFlux work on boundedElastic, a Quarkus blocking resource method or managed executor task, and a scheduled run.

• To read the maps, the sensor asks Instrumentation.redefineModule to open java.lang to the agent's own module only, never to the application. Without the opening the sensor reports itself unavailable; a claim never fails.
• A table larger than 16,384 slots or with more than 4,096 thread locals set is skipped and counted. At most 16 leftovers a scope are reported.

It has no open hook of its own: the files and network sensors hand it what they opened. A resource still open 250 ms after its request ended is counted Open after request, and one closed later Closed after request; both are often an intended hand-off, such as a connection pool's sockets. A resource the collector finds unreachable while never closed is Reclaimed without close(), the leak, and the only count a run comparison keys on. Leave it out of bootui.agent.sensors to turn it off.

• Close hooks: FileInputStream, FileOutputStream, and RandomAccessFile close, FileChannelImpl.implCloseChannel, Socket.close, and AbstractSelectableChannel.implCloseChannel.
• Only the JDK's exact channel and socket classes are tracked, at most 1,024 at a time, each as a weak reference. Nothing captures the resource, its class, or its class loader.
• A resource kind is tracked only while its close hook passed its self-test.

It records the caught exception's class, the handler's site (class, method, line, and declared types), its owner, and its thread. It never records a message, stack trace, or field. Should an application class fail to load with a VerifyError naming CaughtExceptions, remove caught-exceptions from bootui.agent.sensors and report the class.

• Hooks: handler entry (each exception handler that names a type, in the claimed packages) and exceptional exit (each method with such a handler, except constructors). finally and synchronized handlers are left alone.
• Caught exceptions stay pending for at most 60 seconds. A site caught more than 16 times for one owner on a thread is only counted after that.
• The sensor registers at most 16,384 handlers for the JVM's life; the Exceptions panel says when some were left out.
• The inserted code runs only when an exception is caught or leaves a method that catches some.

• A schema change (an added or removed method or field) is refused by the JVM unless it supports enhanced redefinition, as the JetBrains Runtime does.
• On JDK 17, a release or a claim that adds or removes a sensor reverts a HotSwap made since the class loaded. Apply it again, or restart.
• Code Inventory compares a HotSwapped method with the previous run only after the next restart or live reload.

Code Paths' trees, Code Inventory's first calls, and Side Effects' rows are kept in bounded stores of the run, not as runtime journal events. The same rules apply to them as to journal events:

• Panel visibility. While a store's panel or HTTP Exchanges is disabled, the panel, its MCP tool, its CLI command, and the Runtime Insights observations that read it say so and show nothing of its evidence.
• Clear recording. Clear recording and Free BootUI memory drop this evidence too. Counts since the claim and which methods executed are kept.
• Exports. Panels, Export JSON, Copy for AI, MCP tools, and the CLI carry only method keys, route templates (or masked observed paths), request ids, times, and counts.
• Memory. The journal status reports the stores' estimated bytes as Agent evidence, against bootui.runtime-journal.agent-evidence-max-bytes (about 68 MB by default).

get_code_paths and bootui code paths return at most limit (10) routes matching query, slowest first. The diagnose_runtime_issue MCP prompt points to it for a slow route's handler.

• The engine merges a request's fragments into a request tree, then, about two seconds after its last fragment, into the route tree, with a log2 histogram from which the approximate median and 95th percentile are read.
• A node is its caller, its method, and the request phase it was entered in, so response-write time never counts as handler time.
• Route trees are bounded: 2,000 nodes a route (one Other node per parent and phase past the budget), 100,000 nodes and 500 routes across the run.
• The SQL, REST client, cache, and AI recorders take the stamp of the innermost instrumented method open on their thread, so each call is counted under the node that issued it. A call recorded on another thread carries no stamp.
• Assembly only applies to a Spring MVC handler that started async processing, every Spring WebFlux handler, and a Quarkus resource method on the event loop or returning Uni, Multi, CompletionStage, or a publisher.
• The runtime model gains an observed INVOKES edge between two beans per call pair. Change impact never walks it.
• Trees are kept under the agent evidence contract.

AI agents start one with start_method_probe (bootui probe start <method>) and read it with get_method_probe (bootui probe show <id>), only after the user's separate approval; see Did this method run, and how?. Agents start metadata-only probes and never see a shape.

• The probe's own advice counts invocations and checks the window, so a probe never records past its bound even if removing its instrumentation is slow or fails.
• A probe takes a method the inventory or code-paths sensor instrumented, in the application's packages, by binary.Class#name with its descriptor when the method is overloaded.
• The run's last 25 probes, with at most 20 invocations each, are kept under the agent evidence contract.

A shape says what an argument or the return value looked like without saying what it was: its runtime type, whether it was null, and, for a short list of JDK types, a size, a length, or a presence. It never shows a value.

No application code runs: the agent never calls toString(), hashCode(), equals(), a getter, an iterator, or the size() of an application or Hibernate collection, and a lazy Hibernate collection is never initialized.

bootui.expose-values decides what the panel shows, live: under METADATA_ONLY, no shape (and a probe cannot be started with them); under MASKED, the default, types, nullness, sizes, and presence; under FULL (or MASKED with bootui.mask-secrets=false), also string lengths, array lengths, and enum constant names. MCP, the CLI, and exports never return a shape, whatever the exposure.

get_code_inventory and bootui code inventory return the counts first, then at most limit (25) rows of query: changed (the default), never-executed, not-tracked, executed, dependencies, or a package, class, or method name. The verify_after_change MCP prompt starts from it, and Runtime Insights reports a changed method no request executed as changed-code-not-executed.

• At each run, BootUI scans the application's own class files in the claimed packages, off the request path (test roots excluded), and hashes each method over its resolved instructions, never line numbers or other debug attributes. A recompilation with other debug settings or a lambda only renumbered hashes the same; a changed literal, method reference, or @GetMapping value does not.
• The scan is bounded by bootui.code-inventory.max-classes (20,000) and bootui.code-inventory.scan-timeout (30 seconds). Past either, it is partial and says so, and unreadable methods are never reported as removed.
• The previous run's hashes are kept across restarts in the same JVM, at most 1 MB a run per application. A full JVM restart keeps no previous run.
• Which methods executed comes from the agent's hit flags, exactly; the first request, route, and time come from records a full ring may drop (counted, and said).
• A HotSwap shows in Changed only after the next restart or live reload.
• Clear recording drops every first request and route recorded before it; which methods executed still covers the whole run.

Each row is attributed to the request route from HTTP Exchanges, then the execution no request owns (scheduled ReportJob.run, consumed kafka orders, websocket /ws), then startup, then a normalized thread family such as pool-{n}-thread-{n}. The call site is the first application frame, rendered as Class#method. Rows link to Live Activity through up to three exemplar request ids. While HTTP Exchanges is disabled, route rows merge under (route hidden: HTTP Exchanges is disabled).

Rows show what each sensor is allowed to record, never more: process rows show the command name, not arguments; file rows show a path pattern, not contents; environment rows show a name, not a value. Network rows carry how the connection is captured: captured with the panel's id, not-captured, or infrastructure.

Runtime Insights' run comparison reads these rows too: under Outside the JVM it lists the hosts, file patterns, processes, and variable names a route, a job, or startup uses now and did not in the previous run, or no longer uses.

Side Effects is an agent evidence store: Clear recording and Free BootUI memory clear its rows, and the panel then says The recording was cleared. When the panel is disabled, the API, MCP tool, and CLI show only The Side Effects panel is disabled.

get_side_effects and bootui side-effects return every sensor's coverage, then at most limit (20) rows matching query: a sensor id such as processes, network, or blocking, not captured for the connections no panel shows, or part of a route, target, client, or call site, most frequent first. The MCP tool is advertised only while the agent is armed.

• Process rows: starts, failed starts, completed exits, non-zero exits, last exit status, total and longest lifetime.
• Network rows: kind (connect, datagram, or lookup), client, capture state, attempts, failures, and times.
• Files rows: path pattern with its kind (read, write, delete, move from, move to, copy from, copy to), location, and origin. Class path, JDK, and logging rows are grouped apart in a collapsed table.
• Thread-activity rows: kind (thread, virtual thread, or executor), target, origin, how many were started or created, and how many were left running.
• Blocking rows: operation (sleep, wait, or park), event loop family, call site, and inside bean method, with the calls, interruptions, and how long they blocked the loop.
• Rows are capped at 500 per sensor and 2,000 per run; extra observations are counted in the sensor's Other row. These bounds shrink in proportion when bootui.runtime-journal.agent-evidence-max-bytes is set below its default. A request that never receives a route after 30 seconds is (unknown route).
• A comparison shows absence as unknown, and Partial, for an owner whose work is still pending.

The three samples seed routes that show each sensor with the agent attached, each with a counterexample:

• GET /api/side-effects/java-version starts java -version (a java process row); GET /api/side-effects/runtime-version answers from the running JVM and starts no process.
• GET /api/side-effects/sdk-call connects through an SDK-style client with its own java.net.Socket, which reads Not captured by any panel; GET /api/side-effects/rest-call goes through the recorded REST client and is never not captured.
• GET /api/side-effects/report writes a dated report under target/bootui-side-effects and reads the sample.report.title property (with environment opted in); scratch writes to $TMPDIR and log writes through a JDK logging handler.
• The WebFlux and Quarkus samples also seed GET /api/side-effects/event-loop-sleep, which sleeps 50 ms on an event loop, and worker-sleep, the same sleep on a worker thread, which shows no row.