A safe, dynamic tracing tool for the Java platform

BTrace dynamically instruments running Java applications to inject tracing code at runtime, without stopping the application or recompiling code. Similar to DTrace for OpenSolaris, BTrace uses bytecode instrumentation to trace methods, monitor performance, and diagnose issues in production environments.

• Based on ASM
• Powered by JCTools
• Powered by hppcrt
• Optimized with JProfiler Java Profiler
• Build env helper using SDKMAN!

You will need the following applications installed

• Git
• (optionally, the default launcher is the bundled gradlew wrapper) Gradle

cd <btrace>
./gradlew :btrace-dist:build

Output locations:

• Binary distributions: btrace-dist/build/distributions/ (*.tar.gz, *.zip, *.rpm, *.deb)
• Exploded binary (BTRACE_HOME): btrace-dist/build/resources/main/

Updating golden files: When instrumentor code changes, update test golden files with:

./gradlew test -PupdateTestData

Commit the regenerated golden files to Git.

Download: Get the latest release from the release page

Binary distribution:

# Extract the archive
tar -xzf btrace-*.tar.gz
# or
unzip btrace-*.zip

# Set environment variables (optional but recommended)
export BTRACE_HOME=/path/to/btrace
export PATH=$BTRACE_HOME/bin:$PATH

Package installation:

# RPM-based systems
sudo rpm -i btrace-*.rpm

# Debian-based systems
sudo dpkg -i btrace-*.deb

Docker images:

# Copy BTrace into your application image
FROM btrace/btrace:latest AS btrace
FROM bellsoft/liberica-openjdk-debian:11-cds

COPY --from=btrace /opt/btrace /opt/btrace
ENV BTRACE_HOME=/opt/btrace PATH="${PATH}:${BTRACE_HOME}/bin"

# Your application...

Available variants:

• btrace/btrace:latest - Debian-based (~25MB)
• btrace/btrace:latest-alpine - Alpine-based (~15MB)
• btrace/btrace:latest-distroless - Distroless (~10MB)

See docker/README.md for complete Docker documentation.

# Attach to running application
btrace <PID> <trace_script.java>

# Compile BTrace script
btracec <trace_script.java>

# Launch application with BTrace agent
btracer <compiled_script.class> <java-application-and-args>

For comprehensive documentation, tutorials, and guides:

• BTrace Documentation Hub - Complete documentation index with learning paths, quick reference, troubleshooting, and more
• Getting Started Guide - Get up and running in 5 minutes
• BTrace Wiki - External wiki with additional resources

The BTrace Maven Plugin enables:

• Compilation of BTrace scripts during the build process
• BTrace Project Archetype for quick project setup

Important: Pull requests can only be accepted from signers of the Oracle Contributor Agreement.

See CLAUDE.md for detailed development guidelines and project architecture.

• Slack: btrace.slack.com
• Gitter: gitter.im/btraceio/btrace
• Issues: GitHub Issues

BTrace is licensed under GPLv2 with the Classpath Exception. See LICENSE for details.