Trace a live JVM in one lineYour coding agent writes, attaches and removes the probeNo overhead after you detachScripts half the size with the flat DSLLLM, RAG and inference observability from inside the JVMExtensions with permissions you grantOne jar, Apache 2.0Ready for class files newer than ASM supports2.x probes run unchangedJava 8 through 27Trace a live JVM in one lineYour coding agent writes, attaches and removes the probeNo overhead after you detachScripts half the size with the flat DSLLLM, RAG and inference observability from inside the JVMExtensions with permissions you grantOne jar, Apache 2.0Ready for class files newer than ASM supports2.x probes run unchangedJava 8 through 27
SYS:// btrace 3.0.0first major since 2.2.6status: online

Ask your agent. It traces the live JVM.

BTrace adds instrumentation to a JVM while it runs. You do not restart it. In 3.0, your coding agent can operate it. Describe the symptom. The btrace-observability plugin writes a narrow probe, attaches it, reads the output and removes it.

  1. [01]No file, no compile.One command attaches to a live JVM.→
  2. [02]Your coding agent can run it.In Claude Code, Codex and Pi.→
  3. [03]Production-safe attach.Check the JVM first. No overhead after you detach.→
[ claude :: checkout-service :: on-call ] done // probe removed
> you Checkout is sometimes slow, and some orders do not complete. The logs show nothing. We cannot restart the service. Find the cause.
list_jvms Found CheckoutServiceApp
Read PaymentClient and FraudScreen come from acme-sdk.jar, which has no source
deploy_script Measure FraudScreen.screen (return, error) and PaymentClient.authorize. Report every 5 s.
read_probe_output wait_seconds: 12
exit_probe Probe removed
list_probes No probes running
> agent // diagnosis FraudScreen.screen calls threw RiskServiceException : 22 of 104 (21%). checkout swallows it, so those orders are dropped without a log line. PaymentClient.authorize: 129 ms average, 449 ms worst. Probe removed.
// live probe output
$ list_jvms
48211 CheckoutServiceApp
$ deploy_script CheckoutProbe.java → 48211
probe attached, @OnTimer(5000)
$ read_probe_output --wait 12
=== checkout probe ===
FraudScreen.screen 104 calls 22 errors (21%)
RiskServiceException, swallowed by checkout
avg 15 ms max 41 ms
PaymentClient.authorize 76 calls
avg 129 ms max 449 ms
$ exit_probe
probe removed; no overhead remains
$ list_probes
(none)

// Condensed from a recorded Claude Code session (demos/06-ai-assistant). The vendor SDK has no source, so only a live probe could find the cause.

Install the agent plugin

Ships from btraceio/agent-plugins. Needs JBang and JDK 11+ on the machine that runs the target JVM.

› /plugin marketplace add btraceio/agent-plugins
› /plugin install btrace-observability@btraceio-agent-plugins
02 // Start here

What do you want to trace?

Select your role. The page then shows three first steps for that role and filters the tutorial list.

> Find the cause on a live JVM. Then remove all probes.

03 // Agent plugins

One marketplace. Claude Code, Codex, Pi.

Five plugins from one repository. Each works the same way in all three hosts.

// btrace-observability skills btrace-latency-analysis btrace-failure-analysis btrace-oneliner-triage btrace-endpoint-diagnostics btrace-probe-lifecycle btrace-data-safety btrace-runtime-access btrace-startup-and-packaging btrace-mcp-operations btrace-legacy-libs-migration
04 // Oneliners

No file. No compile.

One command attaches to a live JVM and prints the result. Change the matcher and run the command again. Use the builder below to make a command.

// start from a question
Location
if duration >200 ms
Print
// command
$ btrace -n 'OrderService::* @return if duration>200ms { print method, duration }' <PID>
// simulated sample output
chargeCard
execution time: 345 ms
processOrder
execution time: 394 ms
Oneliner Guide → Oneliner to script: the flat DSL →
05 // AI workloads

See your model calls from inside the JVM.

Three bundled extensions measure LLM calls, RAG retrieval and on-device inference. No code change, no restart.

> btrace-llm-trace

Tokens, latency, cost, budgets

Token counts and estimated cost per model. Add btrace-contracts to flag calls over a latency budget.

Model: gpt-4o-mini (openai)
  Calls: 20
  Tokens: 2571 in / 5013 out
  Latency: avg 464ms, max 3635ms
  Est. cost: $0.0034
VIOLATIONS: 1 (5%)
Latency 3635ms exceeded budget 500ms
Tutorial 07 →
> btrace-rag-quality

Retrieval quality

Vector store queries, similarity scores and empty retrievals, which the app does not log.

Source: vectorstore
  Queries: 18 (3 empty, 16%)
  Results: 75 total (avg 4/query)
  Similarity (top): avg 0.730
  Latency: avg 53ms, max 82ms
  Context: 14610 tokens
Tutorial 11 →
> btrace-gpu-bridge

On-device inference

Inference latency and throughput for ONNX Runtime, DJL and TensorFlow Java.

Model: onnx/embed-small
  Inferences: 17
  Latency: avg 13ms, max 23ms
  Batch size: avg 1
  Throughput: 74.6 items/sec
Lesson 12.3 →
Extensions

Eight bundled extensions. You decide what each may do.

Extensions replace libs= profiles and the Aggregations API. Each declares the permissions it needs, and you grant them on the agent side. btrace -le explains why an extension is blocked.

btrace-metrics Latency histograms and stats: p50, p95, p99.
btrace-contracts Latency budgets, call-rate limits, assertions and tagged path profiles.
btrace-otel Sends spans, counters and gauges to an OTLP/HTTP collector.
btrace-statsd Sends metrics to a StatsD endpoint.
btrace-utils Common helper functions for probes.
06 // Production

Attach safely to production JVMs.

Check the JVM before you load a probe. When the client detaches, the probe has no cost.

01

Prepare

-javaagent:btrace.jar=port=0

Start the JVM in prepared mode. It listens on localhost only, requires a token, and instruments nothing.

02

Check

btrace doctor <pid>

Reports whether the JVM is ready, with a scriptable exit code. Loads nothing.

03

Attach and detach

btrace <pid> HotPathProbe.java

The client finds the endpoint and token by itself. On exit, the original bytecode is restored.

// btrace doctor, two JVMs
$ btrace doctor 39936
Status: READY (exit 0)
BTrace endpoint: ready at 127.0.0.1:58103
Authentication: required; credential file readable
Tutorial 12 // Attach to production without fear →
07 // Demos

Seven demos, recorded from real runs.

Each includes the target app, the probe and a run.sh script. CI replays every demo on each push, so the output shown is tested.

AI assistant
A coding agent finds why a checkout service drops orders and stalls inside a vendor SDK with no source. ./run.sh →
08 // Tutorials

Short, practical tutorials.

Each uses the same demo app, shows the expected output after every command, and ends with cleanup.

[08] One JAR to Rule Them All Package BTrace plus an extension into a single -javaagent JAR. ~15 min [09] BTrace in Kubernetes, the Sidecar Way Three container variants; attach across a container boundary. ~15 min [12] Attach to Production Without Fear Prepared mode, btrace doctor, no-flag attach, and nothing left behind. ~10 min
09 // Install

One btrace.jar.

Replaces the three-jar layout. Runs on Java 8 to 27. Support for Java below 17 is deprecated and ends in 4.0.

$ sdk install btrace
FROM 2.x

Compiled probes need no change. Source scripts need a one-line import fix, which scripts/migrate-btrace-script.sh applies. Migration guide →

10 // Docs and community
BTrace> end of transmission_

Ask. Probe. Detach.

Install the agent plugin Download 3.0.0