基于BTrace监控调试Java代码

BTrace是Java的一个动态代码追踪工具,通过编写btrace脚本,它可以动态的向目标应用程序的字节码注入追踪代码,通过修改字节码的方式,达到监控调试和定位问题的目的,是解决线上问题的利器。

BTrace项目的Github主页 https://github.com/btraceio/btrace,本文中示例代码在 https://github.com/cellei/btrace-practice

快速开始

我们使用 BTrace User’s Guide 中的示例来做一个快速开始:

1
2
3
4
5
6
7
8
9
10
11
12
13
import com.sun.btrace.annotations.*;

@BTrace
public class HelloWorld {
@OnMethod(
clazz="java.lang.Thread",
method="start",
location = @Location(Kind.ENTRY)
)
public static void func() {
BTraceUtils.println("about to start a thread!");
}
}

BTrace包下载解压后,把bin目录加入环境变量,执行命令btrace <pid> HelloWorld.java,pid是Java目标程序的进程号,可以使用jps或者ps命令查询到。这样就执行了BTrace脚本程序,每启动一个线程,就会打印出 “about to start a thread!”,BTrace脚本已经正常执行了,不需要重启目标Java程序。

若想要退出BTrace的话,按下ctrl+c,再选择1就可以了,也可以在脚本中使用代码BTraceUtils.Sys.exit(0)来退出。

简单分析一下这段代码,@BTrace注解表明这是一段BTrace脚本,@OnMethod注解以及func方法的参数列表(重载时),指定了要跟踪的目标代码,称为探测点(Probe Point),func方法体内的代码就是跟踪行为(Trace Action),即跟踪到目标代码后所执行的代码。

btrace 命令格式:btrace <pid> <btrace-script>,会直接打印结果到命令行下,也可使用转向命令输出结果到文件,例如btrace <pid> HelloWorld.java > btrace.log

如果执行的BTrace脚本是”.java”源文件,btrace命令执行时会首先编译为字节码,建议预编译为”.class”字节码文件后,再执行编译后的BTrace脚本。

写BTrace脚本并且预编译时,需要引入BTrace的jar包,以Maven本地jar包形式引入如下:

1
2
3
4
5
6
7
8
<dependency>
<groupId>com.sun.btrace</groupId>
<artifactId>btrace-client</artifactId>
<version>1.3.11.2</version>
<type>jar</type>
<scope>system</scope>
<systemPath>${basedir}/src/main/resources/lib/btrace-client.jar</systemPath>
</dependency>

使用限制

由于BTrace脚本会向线上代码中注入字节码,即使退出后,注入的字节码也不会恢复,注入的监控代码依然会执行,所以使用BTrace时有一些限制必须遵守,正因为这些限制,BTrace才能更放心的在线上调试中使用。

  • BTrace脚本中不能创建对象、创建数组、捕获和抛出异常。
  • 不能调用实例或静态方法,只能调用com.sun.btrace.BTraceUtils中的静态方法。
  • 不能把目标程序的类或对象赋值给静态或实例字段。
  • 不能定义外部, 内部, 匿名, 本地类。
  • 不能使用同步synchronized代码块和同步方法。
  • 不能使用forwhile等循环语句。
  • 不能扩展类,父类必须是Object,不允许实现接口。
  • 不能使用assert语句,不能使用Class字面值,例如Class<String> c = String.class;

BTrace注解

注解都在com.sun.btrace.annotations包下,分为类注解、方法注解、方法参数注解、属性注解。

类注解

  • @BTrace:用来指明这个Java类是个BTrace脚本程序,被BTrace编译器和BTrace代理执行。
  • @DTrace及@DTraceRef:是单独给Solaris系统使用的,一般使用不到。

方法注解

  • @OnMethod:用来指定监控的目标代码,它有三个常用属性,clazzmethodlocation
  1. clazz 属性用来指定目标代码的类名,支持全限定名/正则/父类/注解形式。全限定名,例如java.lang.Thread;也可以使用正则表达式匹配,例如/java\\.lang\\..+/;父类或接口的形式,例如+java.lang.Runnable,注解形式,例如`@javax.annotation.Resource`。内部类使用$符号连接。
  2. method 属性用来指定目标代码的方法名,支持全限定名/正则/注解形式,特殊的,指定构造方法时使用<init>表示,目标类有重载的方法时,根据@OnMethod修饰的方法的参数列表具体指明哪个目标方法。
  3. location 属性指定目标代码的拦截时机,比如是进入目标方法时拦截(默认),还是目标方法返回值的时候拦截,后面会详细讲到。
  • @OnTimer:用来周期性的、每隔N毫秒定期执行该注解修饰的方法,例如@OnTimer(4000)表示每间隔4000毫秒执行一次。
  • @OnError:当BTrace脚本中其他任何跟踪行为发生异常时,该注解修饰的方法会被执行。
  • @OnExit:当BTrace脚本使用代码BTraceUtils.Sys.exit(0)来退出BTrace命令行会话时,该注解修饰的方法会被执行。
  • @OnEvent:当在BTrace客户端命令行下发生外部事件时,该注解修饰的方法会被执行,此注解的值为事件名称,默认值为”SIGINT”。目前,当执行ctrl+c操作时,该注解修饰的方法就会被执行。
  • @OnLowMemory:用来监测JVM中堆内存是否达到阈值,它有两个属性poolthresholdpool指定监测年轻代还是老年代,GC算法不同也会有所不同,threshold指定阈值大小,举例@OnLowMemory(pool = "Tenured Gen",threshold=6000000)
  • @OnProbe:该注解可以用来避免使用BTrace脚本的内部类,需要和xml映射文件配合使用,详见User’s Guide.

拦截时机

@OnMethod注解的location属性指明拦截目标代码的拦截时机,经常使用的有如下几个:

  • Kind.ENTRY:刚进入目标方法时就执行,当没有指明location时,此为默认值。
  • Kind.RETURN:目标方法返回时执行,配合方法参数注解@Duration可以获取目标方法执行时间,单位纳秒。
  • Kind.THROW:目标方法有异常被抛出时。
  • Kind.CATCH:目标方法有异常被捕获时。
  • Kind.ERROR:目标方法有异常没被捕获抛出了方法之外。
  • Kind.CALL:目标方法被调用时。
  • Kind.LINE:目标方法具体某一行被执行时,值为-1表示方法内所有代码行。

方法参数注解

  • @ProbeClassName:目标代码的类名,全限定名,@OnMethod的clazz中定义。
  • @ProbeMethodName:目标代码的方法名,@OnMethod的method中定义。
  • @Duration:目标方法执行时间,与Kind.RETURN配合使用。
  • @Return:目标方法返回值,与Kind.RETURN配合使用。。
  • @Self:目标实例,指向this关键字的值。
  • @TargetInstance:与Kind.CALL一起使用,代表location中定义的监控到的调用实例。
  • @TargetMethodOrField:与Kind.CALL一起使用,代表location中定义的监控到的调用方法与属性。

属性注解

  • @TLS:ThreadLocal变量,可用于在多个拦截方法间通信、共享变量,只能在使用@OnMethod注解的拦截方法中访问。
  • @Export:该注解标注的字段可以被映射到一个jvmstat计数器上,用以暴露给外部的jvmstat客户端(例如jstat)。

使用示例

获取执行时间超过100ms的方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@BTrace
public class DurationDemo {
@OnMethod(
clazz="/com\\.cellei\\.btrace\\.practice\\.controller\\..*/",
method="/.*/",
location = @Location(Kind.RETURN)
)
public static void duration(@ProbeClassName String pcn, @ProbeMethodName String pmn, @Duration long duration) {
//duration单位纳秒
if(duration > 1000000 * 100){
BTraceUtils.println("DurationDemo.duration: " + pcn + "." + pmn + ":" + (duration/1000000) + "ms");
}
}
}

目标方法的某一行是否被执行

1
2
3
4
5
6
7
8
9
10
11
@BTrace
public class AllLines {
@OnMethod(
clazz="/com\\.cellei\\.btrace\\.practice\\.controller\\..*/",
method = "createUser",
location=@Location(value=Kind.LINE, line=24)
)
public static void applines(@ProbeClassName String pcn, @ProbeMethodName String pmn, int line) {
BTraceUtils.println("AllLines.applines: " + pcn + "." + pmn + ":" + line);
}
}

获取目标方法的参数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@BTrace
public class ArgArray {
@OnMethod(
clazz="/com\\.cellei\\.btrace\\.practice\\.controller\\..*/",
method="updateUser",
location = @Location(Kind.ENTRY)
)
public static void userArg(@ProbeClassName String pcn, @ProbeMethodName String pmn, String id, User user) {
//只能使用BTraceUtils中的反射
Field filed = BTraceUtils.field("com.cellei.btrace.practice.model.User", "name");
BTraceUtils.println("ArgArray.userArg<id>: " + id);
BTraceUtils.println("ArgArray.userArg<user>: " + user);
BTraceUtils.printFields(user);
BTraceUtils.println("ArgArray.userArg<user.name>:" + BTraceUtils.get(filed, user));
}
}

获取构造方法的参数及调用栈

1
2
3
4
5
6
7
8
9
10
11
12
@BTrace
public class Constructor {
@OnMethod(
clazz="com.cellei.btrace.practice.model.User",
method="<init>"
)
public static void anyRead(@ProbeClassName String pcn, @ProbeMethodName String pmn, AnyType[] args) {
BTraceUtils.println(pcn+","+pmn);
BTraceUtils.printArray(args);
BTraceUtils.jstack();
}
}

目标方法重载时

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@BTrace
public class Overload {

@OnMethod(
clazz = "com.cellei.btrace.practice.controller.AppController",
method = "getUser"
)
public static void oneArg(@ProbeClassName String pcn, @ProbeMethodName String pmn, String id) {
BTraceUtils.println("Overload.oneArg: " + id);
}

@OnMethod(
clazz = "com.cellei.btrace.practice.controller.AppController",
method = "getUser"
)
public static void twoArg(@ProbeClassName String pcn, @ProbeMethodName String pmn, String name, Integer age) {
BTraceUtils.println("Overload.twoArg: " + name + ":" + age);
}
}

是否有死锁

1
2
3
4
5
6
7
@BTrace
public class Deadlock {
@OnTimer(4000)
public static void print() {
BTraceUtils.deadlocks();
}
}

获取环境变量及JVM参数

1
2
3
4
5
6
7
8
9
10
11
12
@BTrace
public class JInfo {
static {
BTraceUtils.println("System Properties:");
BTraceUtils.printProperties();
BTraceUtils.println("VM Flags:");
BTraceUtils.printVmArguments();
BTraceUtils.println("OS Enviroment:");
BTraceUtils.printEnv();
BTraceUtils.exit(0);
}
}

捕获异常堆栈

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
@BTrace
public class OnThrow {
@TLS
static Throwable currentException;

@OnMethod(
clazz="java.lang.Throwable",
method="<init>"
)
public static void onthrow(@Self Throwable self) {
currentException = self;
}

@OnMethod(
clazz="java.lang.Throwable",
method="<init>"
)
public static void onthrow1(@Self Throwable self, String s) {
currentException = self;
}

@OnMethod(
clazz="java.lang.Throwable",
method="<init>"
)
public static void onthrow1(@Self Throwable self, String s, Throwable cause) {
currentException = self;
}

@OnMethod(
clazz="java.lang.Throwable",
method="<init>"
)
public static void onthrow2(@Self Throwable self, Throwable cause) {
currentException = self;
}

@OnMethod(
clazz="java.lang.Throwable",
method="<init>",
location=@Location(Kind.RETURN)
)
public static void onthrowreturn() {
if (currentException != null) {
BTraceUtils.Threads.jstack(currentException);
BTraceUtils.println("=====================");
currentException = null;
}
}
}

5秒后退出

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@BTrace
public class ProbeExit {
private static volatile int i;

@OnExit
public static void onexit(int code) {
BTraceUtils.println("BTrace program exits!");
}

@OnTimer(1000)
public static void ontime() {
BTraceUtils.println("hello");
i++;
if (i == 5) {
BTraceUtils.Sys.exit(0);
}
}
}