Skip to content

v3.0.0.md

Latest commit

 

History

History
106 lines (92 loc) · 6.73 KB

v3.0.0.md

File metadata and controls

106 lines (92 loc) · 6.73 KB
Raw

BTrace 3.0.0 is the first major release since 2.2.6 (November 2024): a new package namespace, a new license, a single-jar distribution, an extension framework with permissions, a much shorter script syntax, a binary wire protocol, and instrumentation that keeps working on class files newer than the validated ASM ceiling.

Upgrading from 2.x is mostly automatic; read the migration guide first. Everything below is documented in the documentation hub.

Highlights

  • New home: io.btrace. Sources, Maven coordinates (io.btrace:btrace), and the runtime API moved from org.openjdk.btrace. Probes compiled with 2.x keep working: the agent rewrites the old package references when it loads a persisted probe.
  • Apache License 2.0. BTrace was GPLv2 with the Classpath Exception.
  • One jar. btrace.jar is the agent, the client, and the boot artifact at once. Its internal classes are stored as masked classdata (renamed resources the JVM does not see as classes), so ASM, the compiler, and the engine stay invisible to the target application's classpath.
  • Extensions with permissions. Bundle services into isolated, permission-gated extensions (@Injected), manage them with the new btracex CLI, and ship the bundled ones: metrics (HdrHistogram), StatsD, contracts, LLM tracing, RAG quality, GPU bridge, utilities.
  • Flat DSL and auto-imports. Scripts no longer need BTraceUtils. prefixes or import boilerplate; import static io.btrace.BTrace.* and import io.btrace.core.annotations.* are injected for you.
  • Oneliners. btrace -n 'com.acme.*::* @return if duration>100ms { print method, duration }' <pid> deploys a probe without writing a file.
  • Binary wire protocol (V2) is the default, with automatic V1 fallback so 2.x clients and agents still talk to 3.0 ones on dynamic attach.
  • ClassFile API instrumentation backend. The bundled ASM handles class files up to the Java 27 class-file version, the agent's validated ASM ceiling. On JDK 24+ agents, classes newer than that (Java 28 early-access builds today) are instrumented through the JDK's ClassFile API instead; every probe kind and handler parameter works there, with one documented exception (@Duration on SYNC_ENTRY/SYNC_EXIT handlers).
  • Authenticated prepared mode and btrace doctor. Prepared mode is a JVM started with the agent and no startup script, waiting for a later client connection. -javaagent:btrace.jar=port=0 binds a loopback, token-protected endpoint that 3.0 clients discover through the Attach API (a plain -javaagent:btrace.jar does the same on port 2020); btrace doctor <pid> reports readiness before and after attach.
  • Fat agents and containers. The io.btrace.fat-agent Gradle plugin embeds extensions and startup probes into a single -javaagent jar; official Docker images (ghcr.io/btraceio/btrace:3.0.0, -alpine, -distroless) ship the distribution as a layer.
  • AI-assisted debugging. The MCP server now lives in the btraceio/agent-plugins repository as the btrace-observability plugin.
  • Telemetry is opt-in only (telemetry=true agent argument); the default agent start performs no network operation.

Breaking changes

  • org.openjdk.btrace.* sources must be renamed to io.btrace.* (or drop the imports and rely on auto-imports); scripts/migrate-btrace-script.sh does the rewrite. Compiled probes need no change.
  • The btrace-agent.jar / btrace-boot.jar / btrace-client.jar layout is gone; point launch scripts at libs/btrace.jar. Only io.btrace:btrace is published to Maven Central; the btrace-agent, btrace-client, btrace-boot, and btrace-instr artifacts are not.
  • Permissions are declared by extensions and granted on the agent side (allowExtensions=, allowPrivileged=, or the permission policy file); the client has no --grant flag, and the grant= / deny= / grantAll= agent arguments are accepted but have no effect. (The probe-level @RequestPermission(s) annotations seen in 3.0 pre-release builds were removed before release and never existed in 2.x.)
  • The Aggregations API (Aggregations.newAggregation, AggregationFunction, addToAggregation, printAggregation, clearAggregation) was removed. Use the bundled btrace-metrics extension for histograms and stats, or plain counters and maps from BTraceUtils.
  • libs=<profile> and btrace-libs/ profiles were removed, not deprecated: the agent logs an error and loads nothing. Migrate to extensions.
  • Prepared mode (-javaagent:btrace.jar=port=...) now requires authentication before every command and binds loopback only; a 2.x client cannot connect to a 3.0 prepared endpoint (dynamic attach remains compatible). Remote prepared-mode operation is not supported in 3.0.0.
  • The Maven fat-agent plugin was never published and is not part of 3.0; use the Gradle plugin.

Deprecated

  • Running BTrace against a JVM older than Java 17. BTrace 3.0 runs on Java 8–27+, and pre-17 targets keep working throughout 3.x, but the agent and client print a one-time warning. Support for Java < 17 will be removed in 4.0. Suppress the warning with -Dbtrace.suppressJavaDeprecationWarning=true (on the target JVM for the agent notice, on the client JVM for the console notice).

Behavior changes worth knowing

  • Probe handlers are dispatched through invokedynamic call sites that become no-ops when the client exits, so retracting a probe leaves no lingering overhead.
  • btrace --version reports the build commit.

Install

sdk install btrace                       # SDKMAN
jbang io.btrace:btrace:3.0.0 <pid> ...   # JBang
curl -LO https://github.com/btraceio/btrace/releases/download/v3.0.0/btrace-v3.0.0-bin.tar.gz
sudo dpkg -i btrace_3.0.0-1_all.deb      # Debian/Ubuntu (release asset)
sudo rpm -i btrace-3.0.0-1.noarch.rpm    # RPM-based (release asset)
docker pull ghcr.io/btraceio/btrace:3.0.0

Maven: io.btrace:btrace:3.0.0. Gradle plugins: io.btrace.extension, io.btrace.fat-agent.

Learn more