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-c to bring up the BTrace console menu.

Fig.1 - AllMethods.java

package samples;

import org.openjdk.btrace.core.annotations.*;
import static org.openjdk.btrace.core.BTraceUtils.*;

/**
 * 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 public class AllMethods {
    @OnMethod(
        clazz="/javax\\.swing\\..*/",
        method="/.*/"
    )
    public static void m(@ProbeClassName String probeClass, @ProbeMethodName String probeMethod) {
        print(Strings.strcat("entered ", probeClass));
        println(Strings.strcat(".", 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.

Running btrace -h will print out the command usage help.

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.

• noServer - don't start the socket server
• bootClassPath - boot classpath to be used
• systemClassPath - system classpath to be used
• debug - turns on verbose debug messages (true/false)
• trusted - 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
• startupRetransform - enable retransform of all the loaded classes at attach (true/false)
• 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 - colon separated list of tracing scripts to be run at the agent startup

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.