Skip to content

README.md

Latest commit

 

History

History
174 lines (136 loc) · 13.6 KB

README.md

File metadata and controls

174 lines (136 loc) · 13.6 KB
Raw

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 Pointer to the btrace-observability MCP plugin, which ships in the external btraceio/agent-plugins repository 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
QE Agent Reproducible harness probing BTrace's own spec conformance and misuse resilience Contributors, 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

I Want Advanced Features

  1. JFR Integration → Getting Started: JFR Integration, Tutorial Lesson 5
  2. Sampling → Quick Reference: @Sampled, FAQ: Performance
  3. Latency histograms and stats → Getting Started: Histogram Metrics Extension
  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 — the server ships as the btrace-observability plugin in the external btraceio/agent-plugins repository

Documentation by Topic

Core Features

Advanced Features

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 — where to get the external btrace-observability plugin that connects AI assistants to live JVMs

Deployment & Operations

Problem Solving

Integration

Architecture

Hands-On Tutorials

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

Community

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. Read the Contributing Guidelines (contributions are accepted under the Apache License 2.0)
  2. Fork the repository and create a pull request
  3. See Build Instructions for development setup

Version Information

  • Current Version: Check GitHub Releases
  • Java Compatibility: 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 and JDK Compatibility for the tested JDK matrix.
  • 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