skywalking自定义插件开发

打印 上一主题 下一主题

主题 937|帖子 937|积分 2811

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 方法。
  1. public class MingBaoServiceInstrumentation extends ClassInstanceMethodsEnhancePluginDefine {
  2.     // 要拦截的类
  3.     private static final String ENHANCE_CLASS = "com.mingbao.service.MingBaoService";
  4.     // 拦截器的类名
  5.     private static final String INTERCEPT_CLASS = "org.apache.skywalking.apm.plugin.mingbao.service.MingBaoServiceInterceptor";
  6.     /**
  7.      * 定义要拦截的类名
  8.      */
  9.     @Override
  10.     protected ClassMatch enhanceClass() {
  11.         return NameMatch.byName(ENHANCE_CLASS);
  12.     }
  13.     /**
  14.      * 定义要拦截类的方法,以及对应的拦截器
  15.      */
  16.     @Override
  17.     public InstanceMethodsInterceptPoint[] getInstanceMethodsInterceptPoints() {
  18.         return new InstanceMethodsInterceptPoint[] {
  19.                 new InstanceMethodsInterceptPoint() {
  20.                     @Override
  21.                     public ElementMatcher<MethodDescription> getMethodsMatcher() {
  22.                         // 这里是要拦截的方法
  23.                         return named("service");
  24.                     }
  25.                     @Override
  26.                     public String getMethodsInterceptor() {
  27.                         // 定义拦截器的类名
  28.                         return INTERCEPT_CLASS;
  29.                     }
  30.                     @Override
  31.                     public boolean isOverrideArgs() {
  32.                         // 如果有要改方法参数的需求,这里可以设置成true
  33.                         return false;
  34.                     }
  35.                 }
  36.         };
  37.     }
  38.     /**
  39.      * 这里是拦截构造方法,忽略
  40.      */
  41.     @Override
  42.     public ConstructorInterceptPoint[] getConstructorsInterceptPoints() { return null; }
  43. }
复制代码
(3)定义拦截器

① 3种常见的拦截器接口


  • InstanceMethodsAroundInterceptor:实例方法拦截器
  • StaticMethodsAroundInterceptor:静态方法拦截器
  • InstanceConstructorInterceptor:构造方法拦截器
要拦截对应的方法,必须要实现对应的接口。这里以实现 InstanceMethodsAroundInterceptor 接口,拦截实例方法为例。
② 在方法执行前拦截

实现 beforeMethod(EnhancedInstance, Method, Object[], Class[], MethodInterceptResult) 方法,此方法会在被拦截的方法执行前执行。此方法中一般是定义日志链路节点span对象,一个span对象对应着日志链路中的一个节点。

  • 拦截方法参数说明:
  1. 1.EnhancedInstance objInst:被增强的实例,一般用不上
  2. 2.Method method:被拦截的方法
  3. 3.Object[] allArguments:被拦截方法的入参
  4. 4.Class<?>[] argumentsTypes:被拦截方法的入参的类型
  5. 5.MethodInterceptResult result:此参数可以作为被拦截方法的返回参数,如果给此参数赋值了,会阻断被拦截方法的执行,直接返回此参数。
  6.         可以通过defineReturnValue()方法来定义要返回的数据。
复制代码

  • 链路节点对象span的类型:
节点对象都实现了 AbstractSpan 接口,可以借助ContextManager类来创建和获取节点对象。
创建一个span对象后,就会生成一个链路日志的节点。
  1. 1.EntrySpan:入口层span,它会作为一条链路的起点。如接收Http请求的接口层、Dubbo服务的提供方以及MQ消费者。
  2. 2.LocalSpan:中间层span,它会出现在链路的中间节点上。如一个业务方法被调用。
  3. 3.ExitSpan:出口层span,它会作为一条链路的终点。如发送Http请求的工具、Dubbo服务的调用方以及MQ生产者。
复制代码

  • 链路节点对象span常用的设置项
  1. 1.component:组件类型,比如说Tomcat、Dubbo、SpringMVC...可以从ComponentsDefine类中定义好的一些官方组件类型中选,自定义的组件类型是无法在UI中显示出来的。也可以不设置值,默认会显示Unknown。(可选的类型就那么多,一般自定义时根本找不到合适的)。
  2. 2.layer:日志层级,可以从SpanLayer类中选择,一共就5个:DB、RPC_FRAMEWORK、HTTP、MQ和CACHE。可选的也不多,不合适可以不设置,默认会显示Unknown。
  3. 3.tag:日志标签,支持自定义日志字段,可以通过 span.tag(new StringTag("msg"), msg) 的方式来设置。结合后端配置项 core.default.searchableTracesTags可以达到自定义字段搜索的目的。
复制代码
③ 在方法执行后拦截

实现 afterMethod(EnhancedInstance, Method, Object[], Class[], Object) 方法,此方法会在被拦截的方法执行前执行。此方法中一般是将方法的返回数据记录到链路节点对象中。

  • 拦截方法参数说明:
  1. 前4个参数和beforeMethod()方法中一样,介绍下最后那个参数
  2. Object ret:方法的返回数据
复制代码
④ 代码示例
  1. public class MingBaoServiceInterceptor implements InstanceMethodsAroundInterceptor {
  2.     private static final Gson GSON = new Gson();
  3.     /**
  4.      * 在拦截方法前执行
  5.      */
  6.     @Override
  7.     public void beforeMethod(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes, MethodInterceptResult result) throws Throwable {
  8.         // 解析方法入参
  9.         String message = (String) allArguments[0];
  10.         // 初始化span,这里创建了一个EntrySpan
  11.         ContextCarrier contextCarrier = new ContextCarrier();
  12.         AbstractSpan span = ContextManager.createEntrySpan(MethodUtil.generateOperationName(method), contextCarrier);
  13.         // 自定义标签,记录方法入参
  14.         span.tag(new StringTag("req"), req);
  15.         // 下面的参数如果不合适可以不设置
  16.         span.setLayer(SpanLayer.MQ);
  17.         span.setComponent(new OfficialComponent(999, "mbService"));
  18.     }
  19.     /**
  20.      * 在拦截方法后执行
  21.      */
  22.     @Override
  23.     public Object afterMethod(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes, Object ret) throws Throwable {
  24.         // 获取上下文中的span对象
  25.         AbstractSpan span = ContextManager.activeSpan();
  26.         // 自定义标签,记录方法出参
  27.         span.tag(new StringTag("resp"), GSON.toJson(ret));
  28.         // 停止日志记录,移除上下文
  29.         ContextManager.stopSpan();
  30.         // 返回方法出参
  31.         return ret;
  32.     }
  33.     /**
  34.      * 记录方法异常
  35.      */
  36.     @Override
  37.     public void handleMethodException(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes, Throwable t) {
  38.         ContextManager.activeSpan().log(t);
  39.     }
  40. }
复制代码
(4)定义配置文件

在自定义插件模块的resources目录下定义 skywalking-plugin.def 配置文件,该文件用于帮助探针启动时加载插件时,寻找插件拦截点。
注意:自定义插件时,不管是类还是配置文件,都要把apache的许可证注释带上,可以参考其他插件类文件中最上面被注释的那一段。
  1. 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 文件,把上述文件删掉即可。可以使用下面的命令:
  1. zip -d mingbao-service-plugin-8.7.0.jar 'META-INF/*SF' 'META-INF/*RSA'
复制代码
免责声明:如果侵犯了您的权益,请联系站长,我们会及时删除侵权内容,谢谢合作!
回复

使用道具 举报

0 个回复

倒序浏览

快速回复

您需要登录后才可以回帖 登录 or 立即注册

本版积分规则

用户云卷云舒

金牌会员
这个人很懒什么都没写!

标签云

快速回复 返回顶部 返回列表