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

---

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(strcat("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

| 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 · Gitter · GitHub Issues

Contribute: Pull requests require signing the Oracle Contributor Agreement.

---

License

GPLv2 with Classpath Exception. See LICENSE.

---

Credits: Built with ASM, JCTools, hppcrt. Optimized with JProfiler.