IBM Java 診斷系列（四）：擴展 Dump Analyzer 撰寫自訂分析模組

前言與架構概覽

IBM Dump Analyzer 建立於 Diagnostic Tooling Framework for Java (DTFJ) 之上，核心設計為可擴展分析模組架構。每個模組專責分析系統轉儲特定面向，協助診斷特定問題類型。本文逐步說明開發、部署、執行自訂分析模組完整流程。

開發環境建置

1. 安裝 Eclipse IDE。
2. 建立 Java 專案 AnalysisModule，勾選分離原始碼與類別檔目錄。
3. 加入 4 個 JAR 至建置路徑（依序）：
   • dumpAnalyzer.jar
   • dtfj-interface.jar
   • dtfj.jar (Java 5.0+，位於 j9 目錄)
   • dtfj.jar (Java 1.4.2，位於 sov 目錄)
4. 建立套件 mypackage 撰寫模組程式碼。

兩類分析模組介面

1. 實作 IAnalyze：結論導向分析

適用「判斷特定條件」場景（如：是否多處理器、是否死鎖、是否 WebSphere 轉儲）。需實作：

• getShortDescription()：模組簡述。
• doAnalysis()：回傳名稱/值對陣列，供規則引擎評估。

範例：DWAnalyze 檢查處理器數量 > 1。

public String[] doAnalysis() {
    return checkProcessors(getContext().getCurrentImage());
}
private String[] checkProcessors(Image image) {
    try {
        int procNum = image.getProcessorCount();
        return new String[] {"processorCount=" + procNum};
    } catch (DTFJException e) { handleError(...); }
}

建構子中 defineRule("isMultiProcessor", new String[]{"processorCount > 1 TRUE"}) 定義規則，引擎自動評估真假。

2. 實作 IReport：報告導向分析

適用「輸出詳細資訊」場景（如：列出所有執行緒堆疊、系統類型）。需實作：

• getShortDescription()
• produceReport()：回傳 IAnalysisReport 物件，封裝格式化輸出內容。

範例：DWReport 輸出建立轉儲的系統類型。

public IAnalysisReport produceReport() {
    IAnalysisReport ret = allocateReport();
    Image img = ((AnalyzerContext)getContext()).getCurrentImage();
    ret.printLiteral("Image created on " + img.getSystemType());
    return ret;
}

基礎類 AnalyzerBase

提供 IAnalyzerBase 預設實作、規則引擎、錯誤處理、報告配置等實用方法，建議繼承而非直接實作介面。

三種執行環境部署

Eclipse IDE 內執行

Run Configurations：Main Class 設 com.ibm.dtfj.analyzer.base.DumpAnalyzer，Bootstrap Entries 加入 3 個 DTFJ JAR，Program Arguments 傳入轉儲完整路徑 [+ 分析器類別名/腳本路徑]。

命令列執行

1. 將專案匯出為 analyzers.jar。
2. 複製 4 個核心 JAR 至同目錄。
3. 執行：

set BCP=j9/dtfj.jar;j9/dtfj-interface.jar;sov/dtfj.jar
java -cp dumpAnalyzer.jar;analyzers.jar -Xbootclasspath/p:%BCP% com.ibm.dtfj.analyzer.base.DumpAnalyzer  <分析器類別名>

ISA 內執行

1. 匯出 analyzers.jar 替換 ISA plugins 目錄下同名檔。
2. ISA Dump Analyzer 視圖 Optional Parameters 欄位填入分析器完整類別名（如 mypackage.DWAnalyze）。

狀態機語言 (SML) 串聯分析流程

SML 以狀態機概念控制分析流程，關鍵字：import、state、變數指派 {var} = {analyzer}:{rule}、if/else/fi、newState、report、print、error、terminate。副檔名 .sml。

範例腳本 script.sml：

import mypackage.DWAnalyze
import mypackage.DWReport
state start
multi = DWAnalyze:isMultiProcessor
if (multi = true)
  print DWAnalyze detected a multiprocessor dump
else
  print DWAnalyze did not detect find a multiprocessor dump
fi
report DWReport
terminate ok

腳本執行方式

• Eclipse：Run Arguments 加入腳本完整路徑（排在轉儲路徑之後）。
• 命令列：加入 -scriptDir:<目錄> script.sml。
• ISA：Optional Parameters 加入同樣參數。

核心介面與實用類速查

轉儲物件模型關鍵類別

• Image：整個轉儲，含 ImageAddressSpace、ImageProcess、ImageModule、ImageThread、ImageRegister、ImagePointer。
• ManagedRuntime → JavaRuntime：JVM 執行時，可迭代 JavaClassLoader、JavaThread、JavaMonitor、JavaHeap、JIT 編譯方法。
• JavaClassLoader → 類別定義 → 方法/欄位；JavaHeap → 所有物件 → 欄位值。

實用工具類

• DTFJIterator / DTFJSortedIterator：自動處理損壞物件、支援排序迭代。
• SimpleVector：簡化陣列操作。
• ObjectFinder / ClassFinder：快取掃描結果，避免重複遍歷。
• ObjectNavigatorCollection / ObjectNavigator：封裝物件實例存取欄位路徑。
• 包裝器類：VectorWrapper、HashMapWrapper、PropertiesWrapper、ThreadLocalWrapper 解析標準集合內容。

結語

掌握 DTFJ 模型與分析模組開發流程，即可建構專屬診斷工具解決特定問題。本系列四文涵蓋 Dump Analyzer、EVTK、Lock Analyzer、自訂擴展，完整構建 Java 診斷技能樹，助您提升應用程式穩定度與效能。