原文地址:BTrace用戶手冊(cè)<譯>

BTrace(https://btrace.dev.java.net/) 是一個(gè)非常不錯(cuò)的java診斷工具, 最近試著用了一下, 文檔比較少, 主要是看例子吧.

BTrace 中的B表示bytecode, 表明它是在字節(jié)碼層面上對(duì)代碼進(jìn)行trace 用來在運(yùn)行中的java類中注入trace代碼, 并對(duì)運(yùn)行中的目標(biāo)程序進(jìn)行熱交換(hotswap)

術(shù)語

• Probe Point 在何處執(zhí)行trace語句, 這里的"何處"可以是具體的跟蹤地點(diǎn)和執(zhí)行事件, 在BTrace中通過各種注解來指定
• Trace Actions or Actions 在何時(shí)執(zhí)行trace語句
• Action Methods 定義在trace腳本中的trace語句, 具體來說就是腳本中的無返回值靜態(tài)方法(1.2之后可以是非靜態(tài)方法)

BTrace限制
為了保證trace語句只讀, BTrace對(duì)trace腳本有一些限制(比如不能改變被trace代碼中的狀態(tài))

• BTrace class不能新建類, 新建數(shù)組, 拋異常, 捕獲異常
• 不能調(diào)用實(shí)例方法以及靜態(tài)方法(com.sun.btrace.BTraceUtils除外)
• 不能將目標(biāo)程序和對(duì)象賦值給BTrace的實(shí)例和靜態(tài)field
• 不能定義外部, 內(nèi)部, 匿名, 本地類
• 不能有同步塊和方法
• 不能有循環(huán)
• 不能實(shí)現(xiàn)接口, 不能擴(kuò)展類
• 不能使用assert語句, 不能使用class字面值

BTrace例子

// import all BTrace annotations  
import com.sun.btrace.annotations.*;  
// import statics from BTraceUtils class  
import static com.sun.btrace.BTraceUtils.*;  
   
// @BTrace annotation tells that this is a BTrace program  
@BTrace  
class HelloWorld {  
    
    // @OnMethod annotation tells where to probe.  
    // In this example, we are interested in entry  
    // into the Thread.start() method.  
    @OnMethod(  
        clazz="java.lang.Thread",  
        method="start"  
    )  
    void func() {  
        sharedMethod(msg);  
    }  
   
   void sharedMethod(String msg) {  
        // println is defined in BTraceUtils  
        println(msg);  
   }  
}  

方法上的注解

• @com.sun.btrace.annotations.OnMethod 用來指定trace的目標(biāo)類和方法以及具體位置, 被注解的方法在匹配的方法執(zhí)行到指定的位置會(huì)被調(diào)用.
  • "clazz"屬性用來指定目標(biāo)類名, 可以指定全限定類名, 比如"java.awt.Component", 也可以是正則表達(dá)式(表達(dá)式必須寫在"http://"中, 比如"/java\.awt\..+/").
  • "method"屬性用來指定被trace的方法. 表達(dá)式可以參考自帶的例子(NewComponent.java 和 Classload.java, 關(guān)于方法的注解可以參考MultiClass.java). 有時(shí)候被trace的類和方法可能也使用了注解. 用法參考自帶例子WebServiceTracker.java.
  • 針對(duì)注解也是可以使用正則表達(dá)式, 比如像這個(gè)"@/com\.acme\..+/ ", 也可以通過指定超類來匹配多個(gè)類, 比如"+java.lang.Runnable"可以匹配所有實(shí)現(xiàn)了java.lang.Runnable接口的類. 具體參考自帶例子SubtypeTracer.java.
• @com.sun.btrace.annotations.OnTimer 用來指定時(shí)長(ms)執(zhí)行一次trace. 時(shí)長通過"value"屬性指定. 具體參考自帶例子 Histogram.java
• @com.sun.btrace.annotations.OnError 當(dāng)trace代碼拋異常時(shí)該注解的方法會(huì)被執(zhí)行. 如果同一個(gè)trace腳本中其他方法拋異常, 該注解方法也會(huì)被執(zhí)行.
• @com.sun.btrace.annotations.OnExit 當(dāng)trace方法調(diào)用內(nèi)置exit(int)方法(用來結(jié)束整個(gè)trace程序)時(shí), 該注解的方法會(huì)被執(zhí)行. 參考自帶例子ProbeExit.java.
• @com.sun.btrace.annotations.OnEvent 用來截獲"外部"btrace client觸發(fā)的事件, 比如按Ctrl-C 中斷btrace執(zhí)行時(shí)將執(zhí)行使用了該注解的方法, 該注解的value值為具體事件名稱. 具體參考例子HistoOnEvent.java
• @com.sun.btrace.annotations.OnLowMemory 當(dāng)內(nèi)存超過某個(gè)設(shè)定值將觸發(fā)該注解的方法, 具體參考MemAlerter.java
• @com.sun.btrace.annotations.OnProbe //我也沒搞明白:(

參數(shù)上的注解

• @com.sun.btrace.annotations.Self 用來指定被trace方法的this, 可參考例子AWTEventTracer.java 和 AllCalls1.java
• @com.sun.btrace.annotations.Return 用來指定被trace方法的返回值, 可參考例子Classload.java
• @com.sun.btrace.annotations.ProbeClassName (since 1.1) 用來指定被trace的類名, 可參考例子AllMethods.java
• @com.sun.btrace.annotations.ProbeMethodName (since 1.1) 用來指定被trace的方法名, 可參考例子WebServiceTracker.java
  o (since 1.2)可以通過注解的fqn boolean屬性來表明是否要獲取全限定方法名
• @com.sun.btrace.annotations.TargetInstance (since 1.1) 用來指定被trace方法內(nèi)部被調(diào)用到的實(shí)例, 可參考例子AllCalls2.java
• @com.sun.btrace.annotations.TargetMethodOrField (since 1.1) 用來指定被trace方法內(nèi)部被調(diào)用的方法名, 可參考例子AllCalls1.java 合 AllCalls2.java
  o (since 1.2) 可通過注解的fqn boolean屬性來表明是否要獲取全限定方法名
  未被注解的方法參數(shù)
  未使用注解的方法參數(shù)一般都是用來做方法簽名匹配用的, 他們一般和被trace方法中參數(shù)出現(xiàn)的順序一致. 不過他們也可以與注解方法交錯(cuò)使用, 如果一個(gè)參數(shù)類型聲明為AnyType[], 則表明它按順序"通吃"方法所有參數(shù). 未注解方法需要與Location結(jié)合使用:
  Kind.ENTRY, Kind.RETURN- 被trace方法參數(shù)
  Kind.THROW - 拋異常
  Kind.ARRAY_SET, Kind.ARRAY_GET - 數(shù)組索引
  Kind.CATCH - 捕獲異常
  Kind.FIELD_SET - 屬性值
  Kind.LINE - 行號(hào)
  Kind.NEW - 類名
  Kind.ERROR - 拋異常

屬性上的注解

• @com.sun.btrace.annotations.Export 該注解的靜態(tài)屬性主要用來與jvmstat計(jì)數(shù)器做關(guān)聯(lián). 使用該注解之后, btrace程序就可以向jvmstat客戶端(可以用來統(tǒng)計(jì)jvm堆中的內(nèi)存使用量)暴露trace程序的執(zhí)行次數(shù), 具體可參考例子ThreadCounter.java
• @com.sun.btrace.annotations.Property 使用了該注解的trace腳本將作為MBean的一個(gè)屬性, 一旦使用該注解, trace腳本就會(huì)創(chuàng)建一個(gè)MBean并向MBean服務(wù)器注冊(cè), 這樣JMX客戶端比如VisualVM, jconsole就可以看到這些BTrace MBean. 如果這些被注解的屬性與被trace程序的屬性關(guān)聯(lián), 那么就可以通過VisualVM 和jconsole來查看這些屬性了. 具體可參考例子ThreadCounterBean.java 和 HistogramBean.java.
• @com.sun.btrace.annotations.TLS 用來將一個(gè)腳本變量與一個(gè)ThreadLocal變量關(guān)聯(lián). 因?yàn)門hreadLocal變量是跟線程相關(guān)的, 一般用來檢查在同一個(gè)線程調(diào)用中是否執(zhí)行到了被trace的方法. 具體可參考例子OnThrow.java 和 WebServiceTracker.java

類上的注解

• @com.sun.btrace.annotations.DTrace 用來指定btrace腳本與內(nèi)置在其腳本中的D語言腳本關(guān)聯(lián), 具體參考例子DTraceInline.java.
• @com.sun.btrace.annotations.DTraceRef 用來指定btrace腳本與另一個(gè)D語言腳本文件關(guān)聯(lián). 具體參考例子DTraceRefDemo.java.
• @com.sun.btrace.annotations.BTrace 用來指定該java類為一個(gè)btrace腳本文件.