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–25+. 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.

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
curl -LO https://github.com/btraceio/btrace/releases/latest/download/btrace-bin.tar.gz

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

Documentation

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.

Using BTrace

Installation

JBang (Easiest - Recommended)

Use JBang to run BTrace without manual installation: