Home

BTrace

Safe, dynamic tracing tool for Java. BTrace works by dynamically (bytecode) instrumenting classes of a running Java program. BTrace inserts tracing actions into the classes of a running Java program and hotswaps the traced program classes.

Quick Start

To start, type btrace <PID> AllMethods.java with the being a PID of any java application.

This sample trace script (AllMethods.java) will instrument all the methods of all the classes from javax.swing.* packages and the instrumentation will print out the full class and method name upon entering any such instrumented method.

All the output will go to stdout.

While the script is active you can press Ctrl-o to bring up the BTrace console menu.

Fig.1 - AllMethods.java

package samples;

// import BTrace annotations
import net.java.btrace.annotations.ProbeMethodName;
import net.java.btrace.annotations.OnMethod;
import net.java.btrace.annotations.BTrace;
import net.java.btrace.annotations.ProbeClassName;
// "Printer" extension defines methods to print out the data in textual format
import static net.java.btrace.ext.Printer.*;

/**
 * This script traces method entry into every method of 
 * every class in javax.swing package! Think before using 
 * this script -- this will slow down your app significantly!!
 */
// @BTrace annotation is used distinguish the trace files from simple Java
@BTrace public class AllMethods {
    // Inject the instrumentation right after any method from javax.swing package has been entered
    // "/<string>/" syntax denotes a regular expression
    @OnMethod(
        clazz="/javax\\.swing\\..*/",
        method="/.*/"
    )
    // @ProbeClassName and @ProbeMethodName allow the access to the info about the actually probed method
    public static void m(@ProbeClassName String probeClass, @ProbeMethodName String probeMethod) {
        print("entered " + probeClass);
        println("." + probeMethod);
    }
} 

Running BTrace in Detail

Dynamically Attaching to Application

Useful for quickly attaching to an already running application, obtaining the data of interest and detaching, removing any tracing code.

The command for attaching is:

btrace [-p <port>] [-cp <classpath>] <pid> <btrace-script> [<args>]

• port is the port in which BTrace agent listens. This is optional argument. classpath is set of directories, jar files where BTrace searches for classes during compilation. Default is ".".
• pid is the process id of the traced Java program
• btrace-script is the trace program. If it is a ".java", then it is compiled before submission. Or else, it is assumed to be pre-compiled [i.e., it has to be a .class] and submitted.

Starting Application with BTrace

In this mode BTrace is started even before the application startup code is run. This gives us chance to trace the code executed very early in the application's lifecycle.

The syntax for starting an application with BTrace agent

java -javaagent:btrace-agent.jar=[<agent-arg>[,<agent-arg>]*]? <launch-args>

The agent takes a list of comma separated arguments.

• bootClassPath - boot classpath to be used
• systemClassPath - system classpath to be used
• debug - turns on verbose debug messages (true/false)
• unsafe - do not check for btrace restrictions violations (true/false)
• dumpClasses - dump the transformed bytecode to files (true/false)
• dumpDir - specifies the folder where the transformed classes will be dumped to
• stdout - redirect the btrace output to stdout instead of writing it to an arbitrary file (true/false)
• probeDescPath - the path to search for probe descriptor XMLs
• scriptdir - the path to a directory containing scripts to be run at the agent startup
• scriptOutputFile - the path to a file the btrace agent will store its output
• script - comma separated list of tracing scripts to be run at the agent startup; this argument MUST be the last one in the argument list

The scripts to be run must have already been compiled to bytecode (a .class file) by btracec.

When no custom agent arguments are required the btracer utility script may be used instead.