原文地址:BTrace用戶手冊<譯>
BTrace(https://btrace.dev.java.net/) 是一個非常不錯的java診斷工具, 最近試著用了一下, 文檔比較少, 主要是看例子吧.
BTrace 中的B表示bytecode, 表明它是在字節碼層面上對代碼進行trace 用來在運行中的java類中注入trace代碼, 并對運行中的目標程序進行熱交換(hotswap)
術語
- Probe Point 在何處執行trace語句, 這里的"何處"可以是具體的跟蹤地點和執行事件, 在BTrace中通過各種注解來指定
- Trace Actions or Actions 在何時執行trace語句
- Action Methods 定義在trace腳本中的trace語句, 具體來說就是腳本中的無返回值靜態方法(1.2之后可以是非靜態方法)
BTrace限制
為了保證trace語句只讀, BTrace對trace腳本有一些限制(比如不能改變被trace代碼中的狀態)
- BTrace class不能新建類, 新建數組, 拋異常, 捕獲異常
- 不能調用實例方法以及靜態方法(com.sun.btrace.BTraceUtils除外)
- 不能將目標程序和對象賦值給BTrace的實例和靜態field
- 不能定義外部, 內部, 匿名, 本地類
- 不能有同步塊和方法
- 不能有循環
- 不能實現接口, 不能擴展類
- 不能使用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的目標類和方法以及具體位置, 被注解的方法在匹配的方法執行到指定的位置會被調用.
- "clazz"屬性用來指定目標類名, 可以指定全限定類名, 比如"java.awt.Component", 也可以是正則表達式(表達式必須寫在"http://"中, 比如"/java\.awt\..+/").
- "method"屬性用來指定被trace的方法. 表達式可以參考自帶的例子(NewComponent.java 和 Classload.java, 關于方法的注解可以參考MultiClass.java). 有時候被trace的類和方法可能也使用了注解. 用法參考自帶例子WebServiceTracker.java.
- 針對注解也是可以使用正則表達式, 比如像這個"@/com\.acme\..+/ ", 也可以通過指定超類來匹配多個類, 比如"+java.lang.Runnable"可以匹配所有實現了java.lang.Runnable接口的類. 具體參考自帶例子SubtypeTracer.java.
- @com.sun.btrace.annotations.OnTimer 用來指定時長(ms)執行一次trace. 時長通過"value"屬性指定. 具體參考自帶例子 Histogram.java
- @com.sun.btrace.annotations.OnError 當trace代碼拋異常時該注解的方法會被執行. 如果同一個trace腳本中其他方法拋異常, 該注解方法也會被執行.
- @com.sun.btrace.annotations.OnExit 當trace方法調用內置exit(int)方法(用來結束整個trace程序)時, 該注解的方法會被執行. 參考自帶例子ProbeExit.java.
- @com.sun.btrace.annotations.OnEvent 用來截獲"外部"btrace client觸發的事件, 比如按Ctrl-C 中斷btrace執行時將執行使用了該注解的方法, 該注解的value值為具體事件名稱. 具體參考例子HistoOnEvent.java
- @com.sun.btrace.annotations.OnLowMemory 當內存超過某個設定值將觸發該注解的方法, 具體參考MemAlerter.java
- @com.sun.btrace.annotations.OnProbe //我也沒搞明白:(
參數上的注解
- @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方法內部被調用到的實例, 可參考例子AllCalls2.java
- @com.sun.btrace.annotations.TargetMethodOrField (since 1.1) 用來指定被trace方法內部被調用的方法名, 可參考例子AllCalls1.java 合 AllCalls2.java
o (since 1.2) 可通過注解的fqn boolean屬性來表明是否要獲取全限定方法名
未被注解的方法參數
未使用注解的方法參數一般都是用來做方法簽名匹配用的, 他們一般和被trace方法中參數出現的順序一致. 不過他們也可以與注解方法交錯使用, 如果一個參數類型聲明為AnyType[], 則表明它按順序"通吃"方法所有參數. 未注解方法需要與Location結合使用:
Kind.ENTRY, Kind.RETURN- 被trace方法參數
Kind.THROW - 拋異常
Kind.ARRAY_SET, Kind.ARRAY_GET - 數組索引
Kind.CATCH - 捕獲異常
Kind.FIELD_SET - 屬性值
Kind.LINE - 行號
Kind.NEW - 類名
Kind.ERROR - 拋異常
屬性上的注解
- @com.sun.btrace.annotations.Export 該注解的靜態屬性主要用來與jvmstat計數器做關聯. 使用該注解之后, btrace程序就可以向jvmstat客戶端(可以用來統計jvm堆中的內存使用量)暴露trace程序的執行次數, 具體可參考例子ThreadCounter.java
- @com.sun.btrace.annotations.Property 使用了該注解的trace腳本將作為MBean的一個屬性, 一旦使用該注解, trace腳本就會創建一個MBean并向MBean服務器注冊, 這樣JMX客戶端比如VisualVM, jconsole就可以看到這些BTrace MBean. 如果這些被注解的屬性與被trace程序的屬性關聯, 那么就可以通過VisualVM 和jconsole來查看這些屬性了. 具體可參考例子ThreadCounterBean.java 和 HistogramBean.java.
- @com.sun.btrace.annotations.TLS 用來將一個腳本變量與一個ThreadLocal變量關聯. 因為ThreadLocal變量是跟線程相關的, 一般用來檢查在同一個線程調用中是否執行到了被trace的方法. 具體可參考例子OnThrow.java 和 WebServiceTracker.java
類上的注解
- @com.sun.btrace.annotations.DTrace 用來指定btrace腳本與內置在其腳本中的D語言腳本關聯, 具體參考例子DTraceInline.java.
- @com.sun.btrace.annotations.DTraceRef 用來指定btrace腳本與另一個D語言腳本文件關聯. 具體參考例子DTraceRefDemo.java.
- @com.sun.btrace.annotations.BTrace 用來指定該java類為一個btrace腳本文件.
