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.

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.

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

• 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

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

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

• 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

• 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

• 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

• Installation → Getting Started: Installation
• Deployment Modes → Getting Started: Running BTrace
• Fat Agent (Single-JAR) → Getting Started: Fat Agent, Architecture, Gradle Plugin, Maven 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

• 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
• AI / LLM Clients (MCP) → MCP Server for Claude Desktop, Claude Code, Cursor
• Published Extensions → Extension Registry for the catalog format and PR flow

• 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 Registry for the public registry contract
• 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 (Script Compilation): github.com/btraceio/btrace-maven
• Maven Plugin (Fat Agent): Gradle Plugin README
• 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:

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

• 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 documentation label
• Or submit a pull request with improvements

Ready to get started? → Getting Started Guide