B Trace Worksheet

What B Trace Actually Does

B Trace is a Java bytecode instrumentation tool that lets you generate call traces and object interaction logs at runtime. You wrap your application with it, run it, and you get out a trace file you can later analyze. That's the short version. The longer version involves understanding when it helps and when it just adds overhead. I've spent enough time with it on production debugging sessions that I can tell you where people usually get stuck. The tool itself is solid, but the learning curve around setup and trace filtering isn't trivial.

Getting a B Trace Worksheet Running

You'll need B Trace installed, which means Java on your system and the btrace binary somewhere in your PATH. The easiest path is downloading from their official site or pulling it through a package manager if one exists for your OS. Here's the basic command structure: btrace <pid> <script.btrace.java>

The PID is the process ID of the running Java application you want to trace. The script is a BTrace program you write to define what you're looking for. These scripts compile on the fly, which is convenient but means syntax errors stop everything mid-trace. For a minimal worksheet setup, start with something simple. A property monitor script is a good entry point: @PropertyMethod
@Export
public static void getMyField(@TargetInstance Object target) {
    return target.myField;
}

This exports a field value to your trace output without instrumenting every call site. It's one of those patterns that saves you from drowning in noise.

How I Actually Use It Day to Day

The thing most guides don't tell you is that raw trace output from B Trace is enormous. Even a modest application producing a few seconds of execution will generate megabytes of trace data. I've seen sessions where the trace file was larger than the application's own JAR. So filtering at the source matters more than people realize. Instead of tracing everything and hoping you find what you need later, be specific about what you instrument. Use target class names, method names, and argument filters rather than blanked-out probes. One practical workflow I use: write a small BTrace script that instruments only the entry and exit points of methods in the classes I care about, then run the trace with the -f flag to produce a .trace file. After that, I use the btracereplay tool or write a simple script to parse the output.

For parsing, the trace format is basically a sequence of events with timestamps, thread IDs, method signatures, and argument values. You can write a Python script with the btrace library bindings or just use grep and awk if the data isn't too massive. I prefer a small Python script that loads the trace and lets me filter by method name, time window, or specific argument values.

A Real Problem I Hit

Last year I was troubleshooting a memory leak in a web service. The obvious approach was to trace all object allocations, but that produced about forty gigabytes of trace data across a twenty-minute run. The system was thrashing under the instrumentation overhead alone, so the leak behavior changed entirely under B Trace. The workaround was to switch to targeted allocation tracing using the BTrace @OnMethod annotation on java.lang.Object.getClass combined with a call path filter. I only traced allocation sites that were within my application's package hierarchy and below a certain call depth. This cut the trace size from forty GB down to about three hundred megabytes, which was actually processable. It took me a few hours to get the filter script right, but once I had it, the problematic allocation pattern was visible within minutes of running the trace.

Counter-Intuitive Things You Should Know

First, B Trace is not a profiling tool. People keep trying to use it for performance benchmarking, and it's fundamentally the wrong instrument for that job. The overhead is unpredictable and large. Use JMH or Async Profiler for that. B Trace is for answering questions like "what objects passed through this method with these specific argument values?" not "how long did this take?" Second, the compile-on-the-fly behavior is both its greatest strength and its biggest gotcha. When you change a BTrace script and re-run it against a live process, the old instrumentation doesn't cleanly unregister. I've had traces where two versions of the same script ran simultaneously, doubling the output and making it impossible to tell which events came from which script. The fix is to kill and restart the target process between script changes, or use the btrace-client.sh script with the -k flag to kill existing probes before installing new ones.

Limitations Worth Stating Plainly

B Trace only works on Java applications. If you're working in a JVM language like Kotlin, Scala, or Groovy, it works fine since they run on the JVM, but if your application is native C++ or Go, you're looking at a completely different tooling landscape. Don't waste time trying to make it work where it doesn't. The instrumentation overhead is real. Even with minimal probing, expect a performance hit of somewhere between fifteen and forty percent depending on how much you instrument. For a latency-sensitive service, this makes B Trace unusable in production without careful scoping. I typically only run it in staging environments that closely mirror production configuration. Another hard limitation: B Trace cannot instrument methods inside the Java standard library that are loaded by bootstrap class loaders in some configurations. If you're trying to trace core JDK internals and getting silent failures, this is often the reason.

When you need something that handles these cases better, look at Async Profiler for performance analysis or Java Flight Recorder for low-overhead production tracing. B Trace fills a different niche — it's for custom, on-the-fly instrumentation where you need to react to runtime conditions in ways static analysis can't handle.

Download and Setup

You can grab B Trace from their official distribution at btrace.dev or through Maven Central if you're embedding it in a build. The standalone binary distribution includes the compiler, runtime agent, and replay tools all in one package. Extract it, add the bin directory to your PATH, and you're ready to write your first script. Start small. Pick a method in your application you think might be behaving oddly, write a five-line BTrace script that just logs calls to it, and run it. Once you see the trace output and understand the format, everything else builds from there.