[Home]   [TOC]

Updated Sep 29, 2013 by jht5...@gmail.com




BTrace is a safe, dynamic tracing tool for the Java platform. BTrace can be used to dynamically trace a running Java program (similar to DTrace for OpenSolaris applications and OS). BTrace dynamically instruments the classes of the target application to inject tracing code ("bytecode tracing"). Tracing code is expressed in Java programming language. There is also integration with DTrace for the OpenSolaris platform.




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



参数 默认值 说明
bootClassPath boot classpath to be used
systemClassPath system classpath to be used
debug false turns on verbose debug messages (true/false)
unsafe false do not check for btrace restrictions violations (true/false)
dumpClasses false 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
script the path to a script to be run at the agent startup
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

在启动时指定btrace脚本 [4]

java -javaagent:btrace-agent.jar=script=<pre-compiled-btrace-script1>[,<pre-compiled-btrace-script1>]* 
      <MainClass> <AppArguments>


生成简单BTrace的工具 http://hatter.me/js/btrace/


打印所有调用 String.intern() 的堆栈日志:

import com.sun.btrace.AnyType;
import com.sun.btrace.annotations.*;
import static com.sun.btrace.BTraceUtils.*;

public class Trace {

    @OnMethod(clazz = "/.*/", method = "/.*/", location = @Location(value = Kind.CALL, clazz = "java.lang.String", method = "intern"))
    public static void m0(@ProbeClassName String clazz, @ProbeMethodName String method, @TargetInstance Object instance) {
        println("\n==== java.lang.String#intern ====");


Class Annotations

@com.sun.btrace.annotations.DTrace dtrace相关,似乎不能在Linux,Mac下使用 :'(
@com.sun.btrace.annotations.DTraceRef dtrace相关,似乎不能在Linux,Mac下使用 :'(
@com.sun.btrace.annotations.BTrace 标记类为BTrace脚本

Field Annotations

@com.sun.btrace.annotations.Export 将变量导出到外部
@com.sun.btrace.annotations.Property 将变量导出为MXBeant属性
@com.sun.btrace.annotations.TLS 标记BTrace脚本的字段为线程安全

Method Annotations

@com.sun.btrace.annotations.OnMethod 通过函数触发,如是参数调用点、函数调用开始、函数调用结束等
@com.sun.btrace.annotations.OnTimer 定时触发
@com.sun.btrace.annotations.OnError 异常时触发
@com.sun.btrace.annotations.OnExit BTrace退出时触发
@com.sun.btrace.annotations.OnEvent 事件触发,在BTrace运行时可通过Ctrl+C触发事件
@com.sun.btrace.annotations.OnLowMemory 低内存时触发
@com.sun.btrace.annotations.OnProbe -

Argument Annotations

@com.sun.btrace.annotations.Self this对象,当非static函数调用时的this对象
@com.sun.btrace.annotations.Return 返回值
@com.sun.btrace.annotations.ProbeClassName 类名
@com.sun.btrace.annotations.ProbeMethodName 方法名
@com.sun.btrace.annotations.Duration 调用时间
@com.sun.btrace.annotations.TargetInstance 目标对象
@com.sun.btrace.annotations.TargetMethodOrField 目标方法或字段

当出现未打标记的参数时会通过对应类型的切面传递参数,当 AnyType[] 指定时,则会传入剩余的全部参数,传递的参数则依赖于 Location

Kind.ENTRY, Kind.RETURN the probed method arguments
Kind.THROW the thrown exception
Kind.ARRAY_SET, Kind.ARRAY_GET the array index
Kind.CATCH the caught exception
Kind.FIELD_SET the field value
Kind.LINE the line number
Kind.NEW the class name
Kind.ERROR the thrown exception


ClassLoaderDefine.java 打印类加载时的Stacktrace
StringInternTrace.java 打印调用String.intern()的Stacktrace


[1]. http://kenai.com/projects/btrace/pages/UserGuide
[2]. http://docs.oracle.com/javase/6/docs/technotes/guides/instrumentation/index.html
[3]. http://kenai.com/projects/btrace/sources/btrace2/show
[4]. http://macrochen.iteye.com/blog/838920