BTrace Documentation

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.

Quick Start

New to BTrace? Start here → Getting Started Guide

Get up and running in 5 minutes with installation, your first script, and common usage patterns.

Documentation Map

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

Learning Paths

I'm New to BTrace

1. Read Getting Started Guide (10 minutes)
2. Try the 5-minute quick start example
3. Learn Oneliner syntax for quick debugging (5 minutes)
4. Explore BTrace Tutorial lessons 1-3
5. Keep Quick Reference handy

Tip: Want latency histograms fast? See Quick Start: Histogram Metrics Extension and the tutorial section Using the Histogram Metrics Extension.

I Need to Solve a Problem

1. Check Troubleshooting Guide for your error
2. Search FAQ for similar issues
3. Review Getting Started common pitfalls
4. Ask on Slack or Gitter

I Need a Quick Lookup

• 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

I Want Advanced Features

1. JFR Integration → Getting Started: JFR Integration, Tutorial Lesson 5
2. Sampling → Quick Reference: @Sampled, FAQ: Performance
3. Aggregations → Quick Reference: Aggregation Functions
4. Cloud Deployments → Getting Started: K8s, FAQ: K8s
5. Level Filtering → Quick Reference: @Level
6. Extensions Architecture → Extension invokedynamic Bridge

Documentation by Topic

Core Features

• 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

Advanced Features

• 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

Deployment & Operations

• 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

Problem Solving

• No Output → Troubleshooting: No Output
• Attachment Fails → Troubleshooting: JVM Attachment
• Verification Errors → Troubleshooting: Verification
• Performance Issues → Troubleshooting: Performance
• Compatibility → Troubleshooting: Compatibility

Integration

• Spring Boot → FAQ: Spring Boot
• Third-Party Libraries → FAQ: Third-Party
• JMX Export → Quick Reference: @Export, FAQ: Monitoring Integration
• Service Mesh → FAQ: Service Mesh

Architecture

• 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

Sample Scripts

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

External Resources

Official Resources

• GitHub Repository: github.com/btraceio/btrace
• Wiki (External): github.com/btraceio/btrace/wiki
• Maven Plugin: github.com/btraceio/btrace-maven
• Releases: GitHub Releases

Community

• Slack: btrace.slack.com
• Gitter Chat: gitter.im/btraceio/btrace
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Tools & Integrations

• VisualVM Plugin: visualvm.github.io
• JDK Mission Control: For viewing JFR events created by BTrace

Contributing

BTrace is an open-source project welcoming contributions. To contribute:

1. Sign the Oracle Contributor Agreement
2. Read the Contributing Guidelines
3. Fork the repository and create a pull request
4. See Build Instructions for development setup

Version Information

• Current Version: Check GitHub Releases
• Java Compatibility: Java 8-25
• License: GPLv2 with Classpath Exception

Documentation Feedback

Found an issue with the documentation? Please:

• Report it on GitHub Issues
• Tag it with documentation label
• Or submit a pull request with improvements

---

Ready to get started? → Getting Started Guide