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
MCP Server	Using BTrace from AI clients via the Model Context Protocol	AI-assisted debugging, LLM integrations
Migration Guide 2.x → 3.0	Upgrading from BTrace 2.x: package rename, Java version policy, breaking changes	Existing 2.x users
Extension Development Guide	Writing, packaging, and publishing BTrace extensions	Extension authors, platform maintainers
3.0 Release Checklist	JDK, protocol, security, packaging, and RC go/no-go gates	Release maintainers

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. Fat Agent JAR → Getting Started: Fat Agent for single-JAR deployment
6. Level Filtering → Quick Reference: @Level
7. Extensions Architecture → Extension invokedynamic Bridge

I'm Working on AI/LLM Applications

1. Observe LLM API calls → Tutorial Lesson 12.1 — token counts, latency, cost tracking
2. Observe RAG pipelines → Tutorial Lesson 12.2 — vector DB queries, similarity scores
3. Observe on-device inference → Tutorial Lesson 12.3 — ONNX, DJL, TensorFlow
4. Use BTrace from an AI agent → MCP Server for Claude Desktop, Claude Code, Cursor

Documentation by Topic

Core Features

• Method Tracing → Tutorial Lesson 1, Quick Reference: @OnMethod
• Timing & Duration → Quick Reference: @Duration, Pattern: Method 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
• Runtime Contracts → Tutorial Lesson 11 — latency budgets, call-rate limits, assertions, tagged path profiling

AI/LLM Observability

• LLM Inference Tracing → Tutorial Lesson 12.1 — token counts, latency, cost, streaming TTFT
• RAG Pipeline Observability → Tutorial Lesson 12.2 — vector DB queries, similarity scores, empty retrievals
• GPU / Inference Observability → Tutorial Lesson 12.3 — ONNX Runtime, DJL, TensorFlow, Panama FFM
• AI Agents (MCP) → MCP Server — connect Claude Desktop, Claude Code, or Cursor to live JVMs

Deployment & Operations

• Installation → Getting Started: Installation
• Deployment Modes → Getting Started: Running BTrace
• Fat Agent (Single-JAR) → Getting Started: Fat Agent, Architecture, Gradle Plugin
• 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
• AI / LLM Clients (MCP) → MCP Server for Claude Desktop, Claude Code, Cursor
• Published Extensions → Extension Development Guide for writing and publishing extensions

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
• Extension Catalog → Extension Development Guide for packaging and distribution
• Instrumentation Backends (ASM / ClassFile API) → Instrumentation Backends — automatic backend selection for future JDK class files
• Agent Library Attributes → Agent Manifest Library Attributes — declaring boot/system JARs via the agent manifest

Hands-On Tutorials

• Hands-on tutorial series — scenario-driven labs with a runnable demo app; start with Your First Trace in 2 Minutes

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 (Script Compilation): github.com/btraceio/btrace-maven
• Maven fat-agent status: unpublished module removed for 3.0.0; see Getting Started
• 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: BTrace 3.0 runs on Java 8–25+. 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.
• License: Apache License 2.0

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