Welcome to the BTrace documentation! BTrace is a safe, dynamic tracing tool for the Java platform that allows you to instrument running applications without stopping them.
New to BTrace? Start here → Getting Started Guide
Get up and running in 5 minutes with installation, your first script, and common usage patterns.
| Document | Description | Target Audience |
|---|---|---|
| Getting Started | Installation, first script, deployment modes, common pitfalls | New users, quick start |
| Oneliner Guide | DTrace-style oneliners for quick debugging without scripts | Quick debugging, ops/SRE |
| Quick Reference | Annotations, patterns, CLI commands, built-in functions | Experienced users, quick lookup |
| BTrace Tutorial | Comprehensive lessons covering all features | All users, in-depth learning |
| Troubleshooting Guide | Common errors, debugging, performance, compatibility | Problem-solving, debugging |
| FAQ | Common questions, best practices, comparisons | All users, decision-making |
- Read Getting Started Guide (10 minutes)
- Try the 5-minute quick start example
- Learn Oneliner syntax for quick debugging (5 minutes)
- Explore BTrace Tutorial lessons 1-3
- Keep Quick Reference handy
Tip: Want latency histograms fast? See Quick Start: Histogram Metrics Extension and the tutorial section Using the Histogram Metrics Extension.
- Check Troubleshooting Guide for your error
- Search FAQ for similar issues
- Review Getting Started common pitfalls
- Ask on Slack or Gitter
- Quick Debug? → Oneliner Guide for DTrace-style one-line commands
- Annotations? → Quick Reference: Core Annotations
- CLI Commands? → Quick Reference: CLI Commands
- Common Patterns? → Quick Reference: Common Patterns
- Built-in Functions? → Quick Reference: Built-in Functions
- JFR Integration → Getting Started: JFR Integration, Tutorial Lesson 5
- Sampling → Quick Reference: @Sampled, FAQ: Performance
- Aggregations → Quick Reference: Aggregation Functions
- Cloud Deployments → Getting Started: K8s, FAQ: K8s
- Level Filtering → Quick Reference: @Level
- Extensions Architecture → Extension invokedynamic Bridge
- Method Tracing → Tutorial Lesson 1, Quick Reference: @OnMethod
- Timing & Duration → Quick Reference: @Duration, [Pattern: Method Timing](quickReference.md#pattern-1-method-entrye xit-timing)
- Exception Tracking → Quick Reference: Kind.ERROR, Pattern: Exception Tracking
- Field Access → Quick Reference: Kind.FIELD_GET/SET
- JFR Integration → Getting Started: JFR, Quick Reference: @Event, FAQ: JFR
- Sampling → Quick Reference: @Sampled, FAQ: Performance
- Level Control → Quick Reference: @Level
- Aggregations → Quick Reference: Aggregation Functions
- Periodic Events → Quick Reference: @OnTimer, @PeriodicEvent
- Installation → Getting Started: Installation
- Deployment Modes → Getting Started: Running BTrace
- Docker & Containers → Getting Started: Containers
- Kubernetes → Getting Started: K8s, FAQ: Microservices, Troubleshooting: K8s
- Performance Tuning → FAQ: Performance Impact, Troubleshooting: Performance
- Extensions CLI (btracex) → Permission Policy for allow/deny and quick inspection
- No Output → Troubleshooting: No Output
- Attachment Fails → Troubleshooting: JVM Attachment
- Verification Errors → Troubleshooting: Verification
- Performance Issues → Troubleshooting: Performance
- Compatibility → Troubleshooting: Compatibility
- Spring Boot → FAQ: Spring Boot
- Third-Party Libraries → FAQ: Third-Party
- JMX Export → Quick Reference: @Export, FAQ: Monitoring Integration
- Service Mesh → FAQ: Service Mesh
- Masked JAR → Masked JAR Architecture — single-JAR distribution with classdata masking
- v2 Binary Protocol → Version 2 Protocol Architecture — custom binary serialization
- Extension Framework → Extension invokedynamic Bridge, Extension Configuration, Extension Manifest, Extension Storage
- Instrumentation → BTrace Instrumentation Analysis
BTrace includes 50+ sample scripts demonstrating real-world use cases:
- Location:
btrace-dist/src/main/resources/samples/ - Examples: File I/O tracking, JDBC monitoring, HTTP requests, memory allocation, thread analysis
- Browse: BTrace Samples Directory
- GitHub Repository: github.com/btraceio/btrace
- Wiki (External): github.com/btraceio/btrace/wiki
- Maven Plugin: github.com/btraceio/btrace-maven
- Releases: GitHub Releases
- Slack: btrace.slack.com
- Gitter Chat: gitter.im/btraceio/btrace
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- VisualVM Plugin: visualvm.github.io
- JDK Mission Control: For viewing JFR events created by BTrace
BTrace is an open-source project welcoming contributions. To contribute:
- Sign the Oracle Contributor Agreement
- Read the Contributing Guidelines
- Fork the repository and create a pull request
- See Build Instructions for development setup
- Current Version: Check GitHub Releases
- Java Compatibility: Java 8-25
- License: GPLv2 with Classpath Exception
Found an issue with the documentation? Please:
- Report it on GitHub Issues
- Tag it with
documentationlabel - Or submit a pull request with improvements
Ready to get started? → Getting Started Guide