skywalking自定義插件開發-有解無憂

skywalking是使用位元組碼操作技術和AOP概念攔截Java類方法的方式來追蹤鏈路的，由于skywalking已經打包了位元組碼操作技術和鏈路追蹤的背景關系傳播，因此只需定義攔截點即可，

這里以skywalking-8.7.0版本為例，
關于插件攔截的原理，可以看我的另一篇文章：skywalking插件作業原理剖析

1. 創建插件模塊

在 apm-sniffer/apm-sdk-plugin 目錄下創建一個插件maven子模塊，

2. 插件開發

（1）思路

定義攔截點，通常是類的方法
定義攔截器，支持在攔截方法執行前后進行日志采集
定義組態檔，啟用攔截點
編譯打包，將生成的jar放到探針的plugins目錄下

（2）定義攔截點

① 官方提供的攔截點擴展入口

skywalking提供了2種供擴展的攔截點：

ClassInstanceMethodsEnhancePluginDefine：支持定義構造方法和實體方法的攔截點，
ClassStaticMethodsEnhancePluginDefine：支持定義靜態方法的攔截點，

當然還可以直接擴展 ClassEnhancePluginDefine，這個類是上面兩個類的父類，這種方式較為麻煩，一般不推薦使用，

這里以攔截實體方法為例，繼承 ClassInstanceMethodsEnhancePluginDefine 類，

② 類攔截規則

skywalking提供了4種類攔截的規則：

byName：類名匹配（包名+類名）
byClassAnnotationMatch：類注解匹配
byMethodAnnotationMatch：方法注解匹配
byHierarchyMatch：父類或介面匹配

注意：

這里的匹配規則要用字串，不要用類參考的方式（byName(ThirdPartyClass.class.getName())），否則可能會導致探針例外，

注解匹配的方式，不支持繼承的注解

父類或介面匹配的方法，盡量避免使用，否則可能會出現一些難以預料的問題

③ 設定要攔截的類名

實作 enhanceClass() 方法，定義要攔截的類名，必須是全路徑的名稱，即包名+類名，

④ 設定攔截的實體方法和攔截器的類名

實作 getInstanceMethodsInterceptPoints() 方法，定義要攔截的實體方法，以及對應攔截器的類名，攔截器類名也是包名+類名，

這里支持定義多個實體方法，每個實體方法可以使用不同的攔截器，還支持攔截私有方法（private），

⑤ 代碼示例

下面的代碼實作的功能是：使用攔截器 MingBaoServiceInterceptor 攔截 MingBaoService 類的 service 方法，

public class MingBaoServiceInstrumentation extends ClassInstanceMethodsEnhancePluginDefine {
    // 要攔截的類
    private static final String ENHANCE_CLASS = "com.mingbao.service.MingBaoService";
    // 攔截器的類名
    private static final String INTERCEPT_CLASS = "org.apache.skywalking.apm.plugin.mingbao.service.MingBaoServiceInterceptor";

    /**
     * 定義要攔截的類名
     */
    @Override
    protected ClassMatch enhanceClass() {
        return NameMatch.byName(ENHANCE_CLASS);
    }
    /**
     * 定義要攔截類的方法，以及對應的攔截器
     */
    @Override
    public InstanceMethodsInterceptPoint[] getInstanceMethodsInterceptPoints() {
        return new InstanceMethodsInterceptPoint[] {
                new InstanceMethodsInterceptPoint() {
                    @Override
                    public ElementMatcher<MethodDescription> getMethodsMatcher() {
                        // 這里是要攔截的方法
                        return named("service");
                    }
                    @Override
                    public String getMethodsInterceptor() {
                        // 定義攔截器的類名
                        return INTERCEPT_CLASS;
                    }
                    @Override
                    public boolean isOverrideArgs() {
                        // 如果有要改方法引數的需求，這里可以設定成true
                        return false;
                    }
                }
        };
    }
    /**
     * 這里是攔截構造方法，忽略
     */
    @Override
    public ConstructorInterceptPoint[] getConstructorsInterceptPoints() { return null; }
}

（3）定義攔截器

① 3種常見的攔截器介面

InstanceMethodsAroundInterceptor：實體方法攔截器
StaticMethodsAroundInterceptor：靜態方法攔截器
InstanceConstructorInterceptor：構造方法攔截器

要攔截對應的方法，必須要實作對應的介面，這里以實作 InstanceMethodsAroundInterceptor 介面，攔截實體方法為例，

② 在方法執行前攔截

實作 beforeMethod(EnhancedInstance, Method, Object[], Class<?>[], MethodInterceptResult) 方法，此方法會在被攔截的方法執行前執行，此方法中一般是定義日志鏈路節點span物件，一個span物件對應著日志鏈路中的一個節點，

攔截方法引數說明：

1.EnhancedInstance objInst：被增強的實體，一般用不上
2.Method method：被攔截的方法
3.Object[] allArguments：被攔截方法的入參
4.Class<?>[] argumentsTypes：被攔截方法的入參的型別
5.MethodInterceptResult result：此引數可以作為被攔截方法的回傳引數，如果給此引數賦值了，會阻斷被攔截方法的執行，直接回傳此引數，
	可以通過defineReturnValue()方法來定義要回傳的資料，

鏈路節點物件span的型別：

節點物件都實作了 AbstractSpan 介面，可以借助ContextManager類來創建和獲取節點物件，

創建一個span物件后，就會生成一個鏈路日志的節點，

1.EntrySpan：入口層span，它會作為一條鏈路的起點，如接收Http請求的介面層、Dubbo服務的提供方以及MQ消費者，
2.LocalSpan：中間層span，它會出現在鏈路的中間節點上，如一個業務方法被呼叫，
3.ExitSpan：出口層span，它會作為一條鏈路的終點，如發送Http請求的工具、Dubbo服務的呼叫方以及MQ生產者，

鏈路節點物件span常用的設定項

1.component：組件型別，比如說Tomcat、Dubbo、SpringMVC...可以從ComponentsDefine類中定義好的一些官方組件型別中選，自定義的組件型別是無法在UI中顯示出來的，也可以不設定值，默認會顯示Unknown，（可選的型別就那么多，一般自定義時根本找不到合適的），
2.layer：日志層級，可以從SpanLayer類中選擇，一共就5個：DB、RPC_FRAMEWORK、HTTP、MQ和CACHE，可選的也不多，不合適可以不設定，默認會顯示Unknown，
3.tag：日志標簽，支持自定義日志欄位，可以通過 span.tag(new StringTag("msg"), msg) 的方式來設定，結合后端配置項 core.default.searchableTracesTags可以達到自定義欄位搜索的目的，

③ 在方法執行后攔截

實作 afterMethod(EnhancedInstance, Method, Object[], Class<?>[], Object) 方法，此方法會在被攔截的方法執行前執行，此方法中一般是將方法的回傳資料記錄到鏈路節點物件中，

攔截方法引數說明：

前4個引數和beforeMethod()方法中一樣，介紹下最后那個引數
Object ret：方法的回傳資料

④ 代碼示例

public class MingBaoServiceInterceptor implements InstanceMethodsAroundInterceptor {
    private static final Gson GSON = new Gson();
    /**
     * 在攔截方法前執行
     */
    @Override
    public void beforeMethod(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes, MethodInterceptResult result) throws Throwable {
        // 決議方法入參
        String message = (String) allArguments[0];

        // 初始化span，這里創建了一個EntrySpan
        ContextCarrier contextCarrier = new ContextCarrier();
        AbstractSpan span = ContextManager.createEntrySpan(MethodUtil.generateOperationName(method), contextCarrier);
        // 自定義標簽，記錄方法入參
        span.tag(new StringTag("req"), req);

        // 下面的引數如果不合適可以不設定
        span.setLayer(SpanLayer.MQ);
        span.setComponent(new OfficialComponent(999, "mbService"));
    }
    /**
     * 在攔截方法后執行
     */
    @Override
    public Object afterMethod(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes, Object ret) throws Throwable {
        // 獲取背景關系中的span物件
        AbstractSpan span = ContextManager.activeSpan();
        // 自定義標簽，記錄方法出參
        span.tag(new StringTag("resp"), GSON.toJson(ret));

        // 停止日志記錄，移除背景關系
        ContextManager.stopSpan();
        // 回傳方法出參
        return ret;
    }
    /**
     * 記錄方法例外
     */
    @Override
    public void handleMethodException(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes, Throwable t) {
        ContextManager.activeSpan().log(t);
    }
}

（4）定義組態檔

在自定義插件模塊的resources目錄下定義 skywalking-plugin.def 組態檔，該檔案用于幫助探針啟動時加載插件時，尋找插件攔截點，

注意：自定義插件時，不管是類還是組態檔，都要把apache的許可證注釋帶上，可以參考其他插件類檔案中最上面被注釋的那一段，

mingbao-service=org.apache.skywalking.apm.plugin.mingbao.service.MingBaoServiceInstrumentation

3. 使用插件

（1）插件打包

對自定義的插件子模塊執行mvn package操作，構建完成后會生成一個名稱類似 mingbao-service-plugin-8.7.0.jar 的jar包，將jar包拷貝到 skywalking-agent/plugins 目錄下，

（2）使用自定義插件

自定義插件的使用和自帶插件使用方式相同，將 skywalking-agent 打包到專案鏡像中，使用javaagent探針啟動即可，

這里有個建議：如果使用docker來部署專案，可以將 skywalking-agent 目錄放到專案同級目錄下，并在專案同級目錄下構建docker鏡像，因為docker build命令無法操作命令執行目錄的父級目錄所包含的其他檔案，因此要保證 skywalking-agent 要在執行docker build命令的目錄下，

4. 檢查插件生效

啟動專案后，呼叫被攔截的類方法，然后看UI上是否生成了對應的日志，一般情況UI上會延遲幾秒鐘才會生成日志，

5. 可能會遇到的問題

（1）插件不生效

在探針的logs目錄下（docker鏡像部署的專案要先進入鏡像才能看到），會生成 skywalking-api.log 目錄，日志默認級別為 INFO，插件不生效時，一般情況下，日志檔案中一定有錯誤日志，

SecurityException

如果遇到報錯：java.lang.SecurityException: Invalid signature file digest for Manifest main attributes，那么一般是因為自定義插件中依賴了第三方依賴包，在打包時生成了 *.SF 或 *.RSA 檔案，把上述檔案刪掉即可，可以使用下面的命令：

zip -d mingbao-service-plugin-8.7.0.jar 'META-INF/*SF' 'META-INF/*RSA'

轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/551033.html

標籤：Java

上一篇：SpringCloud Gateway 3.x 回應頭添加 Skywalking TraceId

下一篇：返回列表