btrace用法

一、背景 
       在生產環境中可能經常遇到各種問題，定位問題需要獲取程序運行時的數據信息，如方法參數、返回值、全局變量、堆棧信息等。爲了獲取這些數據信息，我們可以 通過改寫代碼，增加日誌信息的打印，再發布到生產環境。通過這種方式，一方面將增大定位問題的成本和週期，對於緊急問題無法做到及時響應；另一方面重新部 署後環境可能已被破壞，很難重新問題的場景。 

二、BTrace功能 
       BTrace天生就爲解決這類問題而來，它可以動態地跟蹤java運行程序。通過hotswap技術，動態將跟蹤字節碼注入到運行類中，對運行代碼侵入較小，對性能上的影響可以忽略不計。 
       BTrace在使用上有很多限制條件，如不能創建對象、數組、拋出和捕獲異常、循環等，具體限制條件參考用戶文檔中的BTrace Restrictions。用戶文檔地址: http://kenai.com/projects/btrace/pages/UserGuide。 
       根據官方聲明，不當地使用btrace可能導致jvm崩潰，如BTrace使用錯誤的.class文件，Hotspot JVM自身存在的hotswap bug等。可以先在本地驗證BTrace腳本的正確性，再傳到生產環境中定位問題。 

    
三、安裝步驟 
1. 下載安裝壓縮包，最新版本的是1.2.1，下載地址: http://kenai.com/projects/btrace/downloads/directory/releases。 
2. 解壓縮，命令腳本放在bin目錄中。 
3. 設置腳本環境變量。 
4. 增加腳本可執行權限。 

四、使用方法 
BTrace主要包含btracec和btrace兩個命令編譯和啓動BTrace腳本: 
1. btrace 
功能: 用於運行BTrace跟蹤程序。 
命令格式: 
btrace [-I <include-path>] [-p <port>] [-cp <classpath>] <pid> <btrace-script> [<args>] 
示例: 
btrace -cp build/  1200 AllCalls1.java 
參數含義: 
include-path指定頭文件的路徑，用於腳本預處理功能，可選； 
port指定BTrace agent的服務端監聽端口號，用來監聽clients，默認爲2020，可選； 
classpath用來指定類加載路徑，默認爲當前路徑，可選； 
pid表示進程號，可通過jps命令獲取； 
btrace-script即爲BTrace腳本；btrace腳本如果以.java結尾，會先編譯再提交執行。可使用btracec命令對腳本進行預編譯。 
args是BTrace腳本可選參數，在腳本中可通過"$"和"$length"獲取參數信息。 

2. btracec 
功能: 用於預編譯BTrace腳本，用於在編譯時期驗證腳本正確性。 
btracec [-I <include-path>] [-cp <classpath>] [-d <directory>] <one-or-more-BTrace-.java-files> 
參數意義同btrace命令一致，directory表示編譯結果輸出目錄。 

3. btracer 
功能: btracer命令同時啓動應用程序和BTrace腳本，即在應用程序啓動過程中使用BTrace腳本。而btrace命令針對已運行程序執行BTrace腳本。 
命令格式: 
btracer <pre-compiled-btrace.class> <application-main-class> <application-args> 
參數說明: 
pre-compiled-btrace.class表示經過btracec編譯後的BTrace腳本。 
application-main-class表示應用程序代碼； 
application-args表示應用程序參數。 
該命令的等價寫法爲: 
java -javaagent:btrace-agent.jar=script=<pre-compiled-btrace-script1>[,<pre-compiled-btrace-script1>]* <MainClass> <AppArguments> 

4. jvisualvm插件 

BTrace提供了jvisualvm插件，強烈推薦在jvisualvm中編寫和測試BTrace腳本，啓動、關閉、發送事件、增加classpath都非常方便。 

五、BTrace實戰 
1. 示例代碼 
示例代碼定義了Counter計數器，有一個add()方法，每次增加隨機值，總數保存在totalCount屬性中。 

package com.learnworld;  
import java.util.Random;  
  
public class BTraceTest {  
  
    public static void main(String[] args) throws Exception {  
        Random random = new Random();  
  
        // 計數器  
        Counter counter = new Counter();  
        while (true) {  
            // 每次增加隨機值  
            counter.add(random.nextInt(10));  
            Thread.sleep(1000);  
        }  
    }  
}  

public class Counter {  
    // 總數  
    private static int totalCount = 0;  
  
    public int add(int num) throws Exception {  
        totalCount += num;  
        sleep();  
        return totalCount;  
    }  
      
    public void sleep() throws Exception {  
        Thread.sleep(1000);  
    }  
  
}  

2. 常見使用場景 
下面通過幾個常見使用場景演示如何使用BTrace腳本。 

1) 獲取add()方法參數值和返回值。 

import com.sun.btrace.annotations.*;  
import static com.sun.btrace.BTraceUtils.*;  
  
@BTrace  
public class TracingScript {  
   @OnMethod(  
      clazz="com.learnworld.Counter",  
      method="add",  
      location=@Location(Kind.RETURN)  
   )  
   public static void traceExecute(int num,@Return int result){  
     println("====== ");  
     println(strcat("parameter num: ",str(num)));  
     println(strcat("return value:",str(result)));  
   }  
}  

import com.sun.btrace.annotations.*;  
import static com.sun.btrace.BTraceUtils.*;  
  
@BTrace  
public class TracingScript {  
   private static Object totalCount = 0;  
     
   @OnMethod(  
      clazz="com.learnworld.Counter",  
      method="add",  
      location=@Location(Kind.RETURN)  
   )   
   public static void traceExecute(@Self com.learnworld.Counter counter){  
     totalCount = get(field("com.learnworld.Counter","totalCount"), counter);  
   }   
      
   @OnTimer(1000)  
   public static void print(){  
     println("====== ");  
     println(strcat("totalCount: ",str(totalCount)));  
   }  
}  

3) 獲取add方法執行時間。 

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

@BTrace
public class TracingScript {
   @TLS private static long startTime = 0;

   @OnMethod(
      clazz="com.learnworld.Counter",
      method="add"
   )
   public static void startExecute(){
     startTime = timeNanos();
   }

   @OnMethod(
      clazz="com.learnworld.Counter",
      method="add",
      location=@Location(Kind.RETURN)
   )
   public static void endExecute(@Duration long duration){
     long time = timeNanos() - startTime;
     println(strcat("execute time(nanos): ", str(time)));
     println(strcat("duration(nanos): ", str(duration)));
   }
}

4) 獲取add()方法調用方法sleep()次數。 

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

@BTrace
public class TracingScript {
   private static long count;

   @OnMethod(
      clazz="/.*/",
      method="add",
      location=@Location(value=Kind.CALL, clazz="/.*/", method="sleep")
   )
   public static void traceExecute(@ProbeClassName String pcm, @ProbeMethodName String pmn,
   @TargetInstance Object instance,  @TargetMethodOrField String method){
     println("====== ");
     println(strcat("ProbeClassName: ",pcm));
     println(strcat("ProbeMethodName: ",pmn));
     println(strcat("TargetInstance: ",str(classOf(instance))));
     println(strcat("TargetMethodOrField : ",str(method)));
     count++;
   }

   @OnEvent
   public static void getCount(){
       println(strcat("count: ", str(count)));
   }
}

六、參考文檔 
1. userGuide: http://kenai.com/projects/btrace/pages/UserGuide 
2. JAVA doc:  http://btrace.kenai.com/javadoc/1.2/index.html 
3. BTrace用戶手冊<譯>，http://macrochen.iteye.com/blog/838920 
4. btrace使用簡介，http://rdc.taobao.com/team/jm/archives/509 
5. btrace記憶,http://agapple.iteye.com/blog/962119 
6. btrace一些你不知道的事(源碼入手)，http://agapple.iteye.com/blog/1005918

原文：http://learnworld.iteye.com/blog/1402763