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
JavaApache-2.0Created 2014-08-28
下载:v2.2.6v2.2.6 ↓2.2.62024-11-09
+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 |

---

 Usin

Top issues

Discussions

Latest release

v2.2.6 v2.2.6 2024-11-09
What'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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON