btraceio /btrace
Production-safe dynamic tracing and diagnostics for Java applications—attach to live JVMs with no restart or recompilation.
★ 5,997⑂ 954👁 310⑃ 525● 474▤ 33
+1
日增长
5,997
stars
954
forks
310
watchers
525
prs
474
issues
33
releases
README
BTrace
Safe, dynamic tracing for Java applications
BTrace dynamically instruments running Java applications to inject tracing code at runtime. No restarts. No recompilation. Built for use on production JVMs.
Quick links: Quick Reference · Step-by-Step Tutorial
---
Why BTrace?
- Zero downtime - Attach to running JVMs without restart
- Safe by design - Scripts are verified against a restricted subset (no loops, no new threads, no external calls) before they are loaded; the subset is designed to avoid side effects on the traced application. Verification does not bound overhead: see production precautions and the misuse-resilience QE
- Flexible probes - Method entry/exit, timings, field access, allocations
- Low overhead - Bytecode is injected only at the probe points you select; cost scales with how hot they are
Supported Java Versions
BTrace 3.0 runs on Java 8–27+. 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 100ms { print method, duration }' $(pgrep -f myapp)
---
Trace Anything
Method timing:
sh
btrace -n 'java.sql.Statement::execute @return { print method, duration }'
Exception tracking:
sh
btrace -n 'java.lang.Exception:: @return { print self, stack(5) }'
Custom probes:
java
@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
The 30-second path above needs nothing else. Alternatives:
sh
JBang by Maven coordinate (no catalog needed, version pinned)
jbang io.btrace:btrace:3.0.0 script.java
SDKMan
sdk install btrace
Manual download (assets are versioned: btrace-v-bin.tar.gz)
BTRACE_VERSION=3.0.0
curl -LO https://github.com/btraceio/btrace/releases/download/v${BTRACE_VERSION}/btrace-v${BTRACE_VERSION}-bin.tar.gz
Docker: copy /opt/btrace from a version-pinned image into your own
FROM ghcr.io/btraceio/btrace:3.0.0 AS btrace
With an installed distribution the commands are btrace (attach), btracec (compile) and btracer (launch with the agent).
Details for every option live in one place each:
- Installation: archives, RPM/DEB packages, JBang, using the agent JAR with -javaagent
- Four ways to run BTrace and the startup-mode security boundary
- Docker images: the Debian, Alpine and distroless variants, tags and Kubernetes patterns
---
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 |
| Wiki | External wiki with additional resources |
---
UsinTop issues
Discussions
#732Where has com.sun.btrace.api.BTraceSettings gone?1 comments · 2025-04-30#728BTrace Roadmap & Call for Feedback0 comments · 2025-02-16#626native mothod could be traced by btrace?1 comments · 2023-05-18#624Missing some functions when instrument a Spring project1 comments · 2023-04-13#622About the OnThrow script in the sample directory1 comments · 2023-03-27#606How to Print Array of Objects passed as paramters to method??1 comments · 2023-01-06#603v2.2.30 comments · 2022-12-23#570How to determine that Btrace script has successfully intruded into the code?1 comments · 2022-08-15
Latest release
v2.2.6 v2.2.6 2024-11-09What's Changed Workaround functional test failures on JDK 22 by @jbachorik in https://github.com/btraceio/btrace/pull/683 Correctly set field name for @TargetMethodOrField by @yewton in https://github.com/btraceio/btrace/pull/700 A bunch of fixes related to Spark 3 on JDK 17 by @jbachorik in https://github.com/btraceio/btrace/pull/703 New Contributors @yewton made their first contribution in https://github.com/btraceio/btrace/pull/693 Full Changelog: https://github.com/btraceio/btrace/compare/v2.2.5...v2.2.6