BT
btraceio/btrace
BTrace - a safe, dynamic tracing tool for the Java platform
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.gzSee 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:buildSee 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.