btraceio/btrace — 6.0k★ on GitHub (Java). Production-safe dynamic tracing and diagnostics for Java applications—attach to live JVMs with no restart or recompilation.
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
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
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 < 17 will be removed in the next major release (4.0). See the migration guide for details on upgrading from BTrace 2.x and the 3.0.0 release notes for everything that changed.
Update instrumentor golden files when bytecode output changes: ./gradlew test -PupdateTestData.
Integration tests (optional):
./gradlew --no-daemon integration-tests:test
These may exercise privileged extensions. If you run into permission denials, provide a policy file and pass it to the test JVMs via -Dbtrace.permissions=/path/to/permissions.properties.
Misuse-resilience QE (optional):
./gradlew :btrace-qe:qe
Runs the abuse corpus in btrace-qe/cases/ against real JVMs and writes a findings report to btrace-qe/build/qe-report/. See the QE Agent guide. Every abuse idea explored so far (kept, rejected, blocked, open leads) is logged in btrace-qe/EXPLORATION.md; check it before proposing new cases.
Using BTrace
Installation
JBang (Easiest - Recommended)
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., 3.0.0)
jbang io.btrace:btrace:<version> <PID> <script.java>
# Or, after `jbang catalog add --name btraceio ...` (see above), use the catalog alias
jbang btrace@btraceio <PID> <script.java>
Note: Replace <version> with the desired BTrace version (e.g., 3.0.0). See releases for available versions.
Extensions: The published artifact bundles the default extensions, so scripts that inject
services such as MetricsService or PrinterService work under jbang with nothing extra to
install.
Benefits: Zero installation, automatic version management, works everywhere (Windows/macOS/Linux/containers), perfect for CI/CD.
Agent JAR: The client automatically discovers the masked agent JAR (btrace.jar) on its classpath — no extraction step is needed. If you want to use the agent JAR directly (e.g., with -javaagent), find it in the Maven local repository after the first jbang run:
For launch-time use, review the startup-mode security boundary. Use noServer=true for startup scripts that do not need later client connections; BTrace 3.0 does not support an unauthenticated remote prepared-mode endpoint.
See Getting Started Guide for complete JBang documentation and examples.
Binary Distribution
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
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 ghcr.io/btraceio/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:
ghcr.io/btraceio/btrace:latest - Debian-based, full tooling
Extensions add functionality via a stable API on bootstrap and an isolated implementation. See the extension development guide and examples.
Note: The legacy libs/profiles mechanism has been removed. Passing libs=<profile> logs an error and loads nothing, so custom classes that used to arrive that way will no longer resolve. Package integrations as extensions and use provided-style class loading patterns (object hand-off + TCCL). For migration guidance and examples, see:
docs/architecture/migrating-from-libs-profiles.md
docs/architecture/provided-style-extensions.md
docs/examples/README.md
As a last resort (discouraged), you may append a single jar to the system classpath: set -Dbtrace.system.appendJar=/abs/path/lib.jar on the target JVM together with the trusted=trueagent argument (-javaagent:btrace.jar=trusted=true,...); the -Dbtrace.trusted system property has no effect and the agent ignores the jar without the agent argument.
Fat Agent JAR (Single-JAR Deployment)
For environments where managing multiple JARs is impractical (Spark, Hadoop, Kubernetes), BTrace provides a fat agent JAR with embedded extensions:
# Build fat agent with the default extensions
./gradlew :btrace-dist:fatAgentJar
# Build with specific extensions only
./gradlew :btrace-dist:fatAgentJar -PembedExtensions=btrace-metrics,btrace-statsd
# Use the fat agent
java -javaagent:btrace-agent-fat.jar <your-app>
The fat agent JAR includes:
All agent and boot classes
Embedded extension API classes (bootstrap)
Embedded extension impl classes (runtime-loaded)
Extension metadata for auto-discovery
For custom fat agent builds, use the Gradle plugin:
plugins {
id 'io.btrace.fat-agent'
}
btraceFatAgent {
embedExtensions {
// BTrace bundles extension packages in its distribution's extensions/ directory.
file('/path/to/btrace-metrics-3.0.0-extension.zip')
project(':my-custom-extension')
}
}
See Fat Agent Plugin Architecture and Gradle Plugin README for details.
Oneliner Quick Examples
BTrace now supports DTrace-style oneliners for quick debugging without writing full Java scripts:
See Oneliner Guide for complete syntax and examples.
Documentation
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
Extensions and Permissions
BTrace supports extensions (like the bundled StatsD extension) that provide additional functionality. Extensions require explicit permissions for security:
Permissions are enforced based on extension/service descriptors and agent grants specified at attach-time.
An extension that declares a privileged permission links only when the operator allows it via agent options (there is no client-side flag), e.g. when starting the target with the agent:
btracex list shows installed extensions; btracex install accepts a local extension package or
separately published third-party Maven coordinates. BTrace-built packages are supplied in the
distribution's extensions/ directory, not as individual Maven artifacts.
Note: Extension “required permissions” are informational and help operators assess risk. Implementation linking is controlled by per‑extension allow/deny lists and the allowPrivileged flag. When an extension is blocked, a plain @Injected field fails the probe deployment fast; only @Injected(optional = true) falls back, and the fallback is a throwing stub by default (mode = SHIM or -Dbtrace.extension.shimMode=shim selects a no-op shim).
Agent Policy and Allow/Deny Lists
Launch-time policy can be set via agent args (operator-controlled):
-javaagent:btrace.jar=...,allowPrivileged=true (every privileged extension; use with caution)
Optional policy file (process-local): -Dbtrace.permissions=/path/to/permissions.properties or ~/.btrace/permissions.properties.
When an extension impl is blocked, the API remains on bootstrap so @Injected(optional = true) fields can be bound to a shim or throwing stub; non-optional fields fail the probe fast.
See docs/PermissionPolicy.md for details and examples.
btracex TUI (interactive)
Launch: btracex inspect (with no args) opens an interactive view of installed extensions.
Header: shows current policy file path and the list of scanned repositories.
Details: selection updates automatically; shows the full-word state: default / allowed / denied and the full path.
Legend: a short legend under the table maps the state symbols.
The TUI provides a keyboard-driven, terminal-based view for browsing installed extensions and toggling their allow/deny state without editing the policy file by hand.
Keys
Navigate: Arrow keys, PageUp/PageDown, Home/End
Toggle state: space (flows ? → + (confirm) → - → +; only c clears to default)
Clear: c (removes extension id from both allow and deny lists)
Explain privileges: e (opens a dialog with required permissions and risk descriptions)
Filter: / (filter by id or path)
Sort: s (choose column; repeat to toggle asc/desc)
Adjust split: m (enter mode), then Up/Down to resize; press Esc or m again to exit
Help / Quit: ? / q
Maven Integration
Fat Agent Plugin: The unpublished in-repository Maven fat-agent module was removed for 3.0.0
because it cannot consume the published 3.0 extension layout safely. Use the
io.btrace.fat-agent Gradle plugin documented above.
Script Compilation Plugin (external repo):
Compilation of BTrace scripts during the build process
BTrace Project Archetype for quick project setup
Telemetry and privacy
BTrace sends no telemetry unless you opt in. The default agent start performs no network operation
and creates no telemetry thread; only the explicit telemetry=true agent argument enables a single
agent_start event. See Getting Started: Optional agent telemetry
for what is sent and how to disable it again.
Contributing
Contributions are accepted under the Apache License 2.0. See CONTRIBUTING.md for the workflow and expectations.
Development
See CLAUDE.md for detailed development guidelines and project architecture.
Community
Slack: btrace.slack.com
Gitter: gitter.im/btraceio/btrace
Issues: GitHub Issues
License
Apache License 2.0. See LICENSE.
Credits: Built with ASM, JCTools, hppcrt. Optimized with JProfiler.
The most recent commit recorded on btraceio/btrace was 3 months ago, based on the GitHub push timestamp. The repository has 953 forks — one of the better signals of community interest.
How many stars does btraceio/btrace have?
btraceio/btrace has 6.0k GitHub stars — refresh the page for the live number, or check github.com/btraceio/btrace. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
Is btraceio/btrace open source?
Yes — btraceio/btrace ships under the Apache-2.0 license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/btraceio/btrace.
What else is in the Backend space?
btraceio/btrace is tracked by TopGit under the Backend category, alongside 11 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
What is btraceio/btrace?
btraceio/btrace (btraceio/btrace) is a Java project on GitHub. From the project's own README: Production-safe dynamic tracing and diagnostics for Java applications—attach to live JVMs with no restart or recompilation.
What language is btraceio/btrace written in?
btraceio/btrace is written primarily in Java. GitHub's language field is based on the largest share of bytes in the default branch.
What license does btraceio/btrace use?
btraceio/btrace is released under the Apache-2.0 license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
Where do I read more about btraceio/btrace?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/btraceio/btrace is the definitive source.
Read full README in the tab above.
Is btrace worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of btrace.