BTrace 3.0.0 is the first major release since 2.2.6 (November 2024): 393 commits, 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 ASM understands.

Upgrading from 2.x is mostly automatic; read the
[migration guide](https://github.com/btraceio/btrace/blob/v3.0.0/docs/Migration-2.x-to-3.0.md)
first. Everything below is documented in the
[documentation hub](https://github.com/btraceio/btrace/blob/v3.0.0/docs/README.md).

## 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 (masked
  classdata keeps ASM, the compiler, and the engine invisible to the target application).
- **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.*` is 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.** On JDK 24+ agents, classes with a class-file version
  newer than the bundled ASM supports (ASM 9.10.1 handles up to Java 27, so Java 28 early-access
  builds today) are instrumented through the JDK's ClassFile API; all probe kinds are supported.
- **Authenticated prepared mode and `btrace doctor`.** `-javaagent:btrace.jar=port=0` binds a
  loopback, token-protected endpoint that 3.0 clients discover through the Attach API;
  `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`](https://github.com/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 (`grant=`,
  `allowExtensions=`, `allowPrivileged=`, or the permission policy file); the client has no
  `--grant` flag. (The probe-level `@RequestPermission(s)` annotations seen in 3.0 pre-release
  builds were removed before release and never existed in 2.x.)
- `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

- `Average` aggregations no longer truncate to `int`; `Minimum`/`Maximum` reset to the correct
  sentinels after `clear()`.
- 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

```sh
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
```

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

## Learn more

- [Getting started](https://github.com/btraceio/btrace/blob/v3.0.0/docs/GettingStarted.md)
- [Hands-on tutorials](https://github.com/btraceio/btrace/blob/v3.0.0/docs/tutorials/README.md)
- [Quick reference](https://github.com/btraceio/btrace/blob/v3.0.0/docs/QuickReference.md)
- [Migration guide](https://github.com/btraceio/btrace/blob/v3.0.0/docs/Migration-2.x-to-3.0.md)