skywalking自定義插件開發_ZenDei技術網路在線

skywalking是使用位元組碼操作技術和AOP概念攔截Java類方法的方式來追蹤鏈路的，由於skywalking已經打包了位元組碼操作技術和鏈路追蹤的上下文傳播，因此只需定義攔截點即可。這裡以skywalking-8.7.0版本為例。關於插件攔截的原理，可以看我的另一篇文章：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'