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.

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., 2.3.0)
jbang org.openjdk.btrace:btrace-client:<version> <PID> <script.java>

# After first run, use shorter alias
jbang btrace <PID> <script.java>

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

Benefits: Zero installation, automatic version management, works everywhere (Windows/macOS/Linux/containers), perfect for CI/CD.

Extract agent JARs (if needed for --agent-jar/--boot-jar flags):

# Extract embedded JARs
jbang btrace --extract-agent ~/.btrace

# This creates ~/.btrace/btrace-agent.jar and ~/.btrace/btrace-boot.jar
# Then use them:
jbang btrace --agent-jar ~/.btrace/btrace-agent.jar --boot-jar ~/.btrace/btrace-boot.jar <PID> <script.java>

# Or find them in Maven local repository (after first jbang run):
# ~/.m2/repository/org/openjdk/btrace/btrace-agent/<version>/btrace-agent-<version>.jar
# ~/.m2/repository/org/openjdk/btrace/btrace-boot/<version>/btrace-boot-<version>.jar

See Getting Started Guide for complete JBang documentation and examples.

Download: Get the latest release from the release page

# 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

# 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.

With JBang (no installation required):

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

# Extract agent JARs
jbang btrace --extract-agent ~/.btrace

With installed BTrace:

# 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>

BTrace now supports DTrace-style oneliners for quick debugging without writing full Java scripts:

# Trace method entry with arguments
btrace -n 'javax.swing.*::setText @entry { print method, args }' <PID>

# Find slow database queries (>100ms)
btrace -n 'java.sql.Statement::execute* @return if duration>100ms { print method, duration }' <PID>

# Count method invocations
btrace -n 'java.util.HashMap::get @entry { count }' <PID>

# Print stack trace on OutOfMemoryError
btrace -n 'java.lang.OutOfMemoryError::<init> @return { stack(10) }' <PID>

Supported features:

• Locations: @entry, @return, @error
• Actions: print, count, time, stack
• Filters: if duration>NUMBERms, if args[N]==VALUE
• Patterns: Wildcards (*, ?) and regex (/pattern/)

See Oneliner Guide for complete syntax and examples.

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

BTrace supports extensions (like StatsdExtension) that provide additional functionality. Extensions require explicit permissions for security:

• Default permissions (always granted): MESSAGING, AGGREGATION, JFR_EVENTS, PROFILING
• Standard permissions (granted unless denied): FILE_READ, SYSTEM_PROPS, THREAD_INFO, MEMORY_INFO
• Privileged permissions (require explicit grant): FILE_WRITE, NETWORK, THREADS, NATIVE, EXEC, REFLECTION, CLASSLOADER, UNLIMITED_MEMORY

Declare required permissions in your probe with @RequestPermission:

@BTrace
@RequestPermission(Permission.NETWORK)
public class MyProbe { ... }

Grant permissions at runtime:

btrace --grant=NETWORK,THREADS <PID> MyProbe.class

If extensions fail to load, use -le to troubleshoot:

btrace -le <PID>

See the Tutorial for detailed documentation.

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.