BTrace

Safe, dynamic tracing for Java applications

BTrace dynamically instruments running Java applications to inject tracing code at runtime. No restarts. No recompilation. Production-safe.

Quick links: Quick Reference · Step-by-Step Tutorial

---

Why BTrace?

• Zero downtime - Attach to running JVMs without restart
• Production safe - Verified scripts can't crash your application
• Flexible probes - Method entry/exit, timings, field access, allocations
• Low overhead - Bytecode injection with minimal performance impact

Supported Java Versions

BTrace 3.0 runs on Java 8–27+. Running BTrace against a JVM older than Java 17 is deprecated: it continues to work throughout 3.x but emits a deprecation warning. Support for Java < 17 will be removed in the next major release (4.0). See the migration guide for details on upgrading from BTrace 2.x and the 3.0.0 release notes for everything that changed.

---

Get Started in 30 Seconds

# Install via JBang (easiest)
curl -Ls https://sh.jbang.dev | bash -s - app setup

# Add the BTrace JBang catalog (one time)
jbang catalog add --name btraceio https://raw.githubusercontent.com/btraceio/jbang-catalog/main/jbang-catalog.json

# Trace slow methods in your running app
jbang btrace@btraceio -n 'com.myapp.*::* @return if duration>100ms { print method, duration }' $(pgrep -f myapp)

---

Trace Anything

Method timing:

btrace -n 'java.sql.Statement::execute* @return { print method, duration }' <PID>

Exception tracking:

btrace -n 'java.lang.Exception::<init> @return { print self, stack(5) }' <PID>

Custom probes:

@BTrace public class Trace {
    @OnMethod(clazz = "com.example.OrderService", method = "checkout")
    public static void onCheckout(@Self Object self, @Duration long ns) {
        println("checkout: " + str(ns / 1_000_000) + "ms");
    }
}

See the Oneliner Guide for complete syntax.

---

Install

# JBang (recommended - zero installation)
jbang catalog add --name btraceio https://raw.githubusercontent.com/btraceio/jbang-catalog/main/jbang-catalog.json
jbang btrace@btraceio <PID> script.java

# SDKMan
sdk install btrace

# Manual download (assets are versioned: btrace-v<version>-bin.tar.gz)
BTRACE_VERSION=3.0.0
curl -LO https://github.com/btraceio/btrace/releases/download/v${BTRACE_VERSION}/btrace-v${BTRACE_VERSION}-bin.tar.gz

See Installation Guide for Docker, package managers, and more options.

---

Documentation

Resource	Description
Quick Reference	Cheat sheet for experienced users
Getting Started	Step-by-step first trace tutorial
Full Tutorial	Complete walkthrough of all features
Oneliners	DTrace-style quick probes
Extensions	StatsD, custom integrations
Documentation Hub	All docs and guides

---

Building from Source

git clone https://github.com/btraceio/btrace.git
cd btrace
./gradlew :btrace-dist:build

See CLAUDE.md for development setup and architecture.

---

Community & Contributing

Get help: Slack · GitHub Issues

Tips:

• Prefer IPv4 if your environment has odd local IPs: set GRADLE_OPTS="-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false".
• Run specific modules:
  • Runtime: ./gradlew :btrace-runtime:test
  • Core (incl. extension SPI): ./gradlew :btrace-core:test
  • Compiler: ./gradlew :btrace-compiler:test
  • Agent (incl. instrumentation): ./gradlew :btrace-agent:test
• Update instrumentor golden files when bytecode output changes: ./gradlew test -PupdateTestData.

Integration tests (optional):

./gradlew --no-daemon integration-tests:test

These may exercise privileged extensions. If you run into permission denials, provide a policy file and pass it to the test JVMs via -Dbtrace.permissions=/path/to/permissions.properties.

Misuse-resilience QE (optional):

./gradlew :btrace-qe:qe

Runs the abuse corpus in btrace-qe/cases/ against real JVMs and writes a findings report to btrace-qe/build/qe-report/. See the QE Agent guide. Every abuse idea explored so far (kept, rejected, blocked, open leads) is logged in btrace-qe/EXPLORATION.md; check it before proposing new cases.

Using BTrace

Installation

JBang (Easiest - Recommended)

Use JBang to run BTrace without manual installation:

# Install JBang (one time)
curl -Ls https://sh.jbang.dev | bash -s - app setup

# Use BTrace immediately (replace <version> with desired version, e.g., 3.0.0)
jbang io.btrace:btrace:<version> <PID> <script.java>

# Or, after `jbang catalog add --name btraceio ...` (see above), use the catalog alias
jbang btrace@btraceio <PID> <script.java>

Note: Replace <version> with the desired BTrace version (e.g., 3.0.0). See releases for available versions.

Extensions: The published artifact bundles the default extensions, so scripts that inject services such as MetricsService or PrinterService work under jbang with nothing extra to install.

This is the beginning of the README. Read the rest at the original. Read the full README ↗