乐趣区

关于java:Skywalking系列博客6手把手教你编写Skywalking插件

jiezi

前置常识

在正式进入编写环节之前，倡议先花一点工夫理解下 javaagent（这是 JDK 5 引入的一个玩意儿，最好理解下其工作原理）；另外，Skywalking 用到了 byte-buddy（一个动静操作二进制码的库），所以最好也相熟下。

当然不理解关系也不大，个别不影响你玩转 Skywalking。

  • javaagent
  • byte-buddy 1.9.6 简述及原理 1

术语

Span: 可了解为一次办法调用，一个程序块的调用，或一次 RPC/ 数据库拜访。只有是一个具备残缺工夫周期的程序拜访，都能够被认为是一个 span。SkyWalking Span 对象中的重要属性

属性 名称 备注
component 组件 插件的组件名称，如：Lettuce，详见:ComponentsDefine.Class。
tag 标签 k- v 构造，要害标签，key 详见：Tags.Class。
peer 对端资源 用于拓扑图，若 DB 组件，需记录集群信息。
operationName 操作名称 若 span=0，operationName 将会搜寻的下拉列表。
layer 显示 在链路页显示，详见 SpanLayer.Class。

Trace: 调用链，通过归属于其的 Span 来隐性的定义。一条 Trace 可被认为是一个由多个 Span 组成的有向无环图（DAG 图），在 SkyWalking 链路模块你能够看到，Trace 又由多个归属于其的 trace segment 组成。

Trace segment:Segment 是 SkyWalking 中的一个概念，它应该包含单个 OS 过程中每个申请的所有范畴，通常是基于语言的单线程。由多个归属于本线程操作的 Span 组成。

TIPS

Skywalking 的这几个术语和 Spring Cloud Sleuth 相似，借鉴自谷歌的 Dapper。我在《Spring Cloud Alibaba 微服务从入门到进阶》课程中有具体分析调用链的实现原理，并且用数据库做了艰深的类比，本文不再赘述。

外围 API

详见 http://www.itmuch.com/books/s… 文章有十分具体的形容。

实战

本文以监控 org.apache.commons.lang3.StringUtils.replace 为例，手把手教你编写 Skywalking 插件。

依赖

首先，创立一个 Maven 我的项目，Pom.xml 如下。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.itmuch.skywalking</groupId>
    <artifactId>apm-string-replace-plugin</artifactId>
    <packaging>jar</packaging>
    <version>1.0.0-SNAPSHOT</version>

    <properties>
        <skywalking.version>6.6.0</skywalking.version>
        <shade.package>org.apache.skywalking.apm.dependencies</shade.package>
        <shade.net.bytebuddy.source>net.bytebuddy</shade.net.bytebuddy.source>
        <shade.net.bytebuddy.target>${shade.package}.${shade.net.bytebuddy.source}</shade.net.bytebuddy.target>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.apache.skywalking</groupId>
            <artifactId>apm-agent-core</artifactId>
            <version>${skywalking.version}</version>
            <scope>provided</scope>
        </dependency>

        <dependency>
            <groupId>org.apache.skywalking</groupId>
            <artifactId>apm-util</artifactId>
            <version>${skywalking.version}</version>
            <scope>provided</scope>
        </dependency>

        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>3.4</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <artifactId>maven-shade-plugin</artifactId>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                        <configuration>
                            <shadedArtifactAttached>false</shadedArtifactAttached>
                            <createDependencyReducedPom>true</createDependencyReducedPom>
                            <createSourcesJar>true</createSourcesJar>
                            <shadeSourcesContent>true</shadeSourcesContent>
                            <relocations>
                                <relocation>
                                    <pattern>${shade.net.bytebuddy.source}</pattern>
                                    <shadedPattern>${shade.net.bytebuddy.target}</shadedPattern>
                                </relocation>
                            </relocations>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>6</source>
                    <target>6</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

这个 Pom.xml 中，除如下依赖以外，其余都得照抄，不论你开发什么框架的 Skywalking 插件， 否则无奈失常构建插件 ！！

<dependency>
  <groupId>org.apache.commons</groupId>
  <artifactId>commons-lang3</artifactId>
  <version>3.4</version>
  <scope>provided</scope>
</dependency>

编写 Instrumentation 类 

public class StringReplaceInstrumentation extends ClassInstanceMethodsEnhancePluginDefine {
    @Override
    protected ClassMatch enhanceClass() {
        // 指定想要监控的类
        return NameMatch.byName("org.apache.commons.lang3.StringUtils");
    }

    @Override
    public ConstructorInterceptPoint[] getConstructorsInterceptPoints() {return new ConstructorInterceptPoint[0];
    }

    @Override
    public InstanceMethodsInterceptPoint[] getInstanceMethodsInterceptPoints() {
        // 指定想要监控的实例办法，每个实例办法对应一个 InstanceMethodsInterceptPoint
        return new InstanceMethodsInterceptPoint[0];
    }

    @Override
    public StaticMethodsInterceptPoint[] getStaticMethodsInterceptPoints() {
        // 指定想要监控的静态方法，每一个办法对应一个 StaticMethodsInterceptPoint
        return new StaticMethodsInterceptPoint[]{new StaticMethodsInterceptPoint() {
                @Override
                public ElementMatcher<MethodDescription> getMethodsMatcher() {
                    // 静态方法名称
                    return ElementMatchers.named("replace");
                }

                @Override
                public String getMethodsInterceptor() {
                    // 该静态方法的监控拦截器类名全门路
                    return "com.itmuch.skywalking.plugin.stringreplace.StringReplaceInterceptor";
                }

                @Override
                public boolean isOverrideArgs() {return false;}
            }
        };
    }
}

编写拦截器 

public class StringReplaceInterceptor implements StaticMethodsAroundInterceptor {
    @Override
    public void beforeMethod(Class aClass, Method method, Object[] argumentsTypes, Class<?>[] classes, MethodInterceptResult methodInterceptResult) {// 创立 span( 监控的开始)，实质上是往 ThreadLocal 对象外面设值
        AbstractSpan span = ContextManager.createLocalSpan("replace");

        /*
         * 可用 ComponentsDefine 工具类指定 Skywalking 官网反对的组件
         * 也可本人 new OfficialComponent 或者 Component
         * 不过在 Skywalking 的管制台上不会被辨认，只会显示 N /A
         */
        span.setComponent(ComponentsDefine.TOMCAT);

        span.tag(new StringTag(1000, "params"), argumentsTypes[0].toString());
        // 指定该调用的 layer，layer 是个枚举
        span.setLayer(SpanLayer.CACHE);
    }

    @Override
    public Object afterMethod(Class aClass, Method method, Object[] objects, Class<?>[] classes, Object o) {String retString = (String) o;
        // 激活 span，实质上是读取 ThreadLocal 对象
        AbstractSpan span = ContextManager.activeSpan();
        // 状态码，任意写，Tags 也是个 Skywalking 的工具类，用来比拟不便地操作 tag
        Tags.STATUS_CODE.set(span, "20000");

        // 进行 span(监控的完结)，实质上是清理 ThreadLocal 对象
        ContextManager.stopSpan();
        return retString;
    }

    @Override
    public void handleMethodException(Class aClass, Method method, Object[] objects, Class<?>[] classes, Throwable throwable) {AbstractSpan activeSpan = ContextManager.activeSpan();
        
        // 记录日志
        activeSpan.log(throwable);
        activeSpan.errorOccurred();}
}

编写配置文件

创立 resources/skywalking-plugin.def，内容如下：

# Key=value 的模式
# key 轻易写；value 是 Instrumentation 类的包名类名全门路
my-string-replace-
plugin=org.apache.skywalking.apm.plugin.stringreplace.define.StringReplaceInstrumentation

构建 

mvn clean install

构建实现后，到 target 目录中，找到 JAR 包 (非 origin-xxx.jar、非 xxx-source.jar )，扔到 agent/plugins 目录外面去，即可启动。

插件调试

插件的编写可能不是一步到位的，有时候可能会报点错什么的。如果想要 Debug 本人的插件，那么须要将你的插件代码和接入 Java Agent 的我的项目（也就是你配置了 -javaagent 启动的我的项目）扔到同一个工作空间内，能够这么玩：

  • 应用 IDEA，关上接入 Java Agent 的我的项目
  • 找到 File->New->Module from Exisiting Sources…，引入你的插件源码即可。

测试与监控成果

想方法让你接入 Java Agent 的我的项目，调用到如下代码 

String replace = StringUtils.replace("oldString", "old","replaced");
System.out.println(replace);

之后，就能够看到相似如下的图啦：

写在最初

本文只是弄了一个简略的例子，解说插件编写的套路。总的来说，插件编写还是十分顺利的，单纯代码的层面，很少会遇到坑；但搜遍各种搜索引擎，居然没有一篇手把手的文章…而且也没有文章解说依赖该如何引入、Maven 插件如何引入。于是只好参考 Skywalking 官网插件的写法，引入依赖和 Maven 插件了，这块反倒是费了点工夫。

此外，如果你想真正把握乃至精通 skywalking 插件编写，最好的方法，还是浏览官网的插件代码，详见：https://github.com/apache/skywalking/tree/master/apm-sniffer/apm-sdk-plugin，轻易挑两款看一下就晓得怎么玩了。我在学习过程中参考的插件代码有：

  • apm-feign-default-http-9.x-plugin
  • apm-jdbc-commons

参考文档

  • Skywalking 插件开发指南
  • SkyWalking apm-sniffer 原理学习与插件编写
  • SkyWalking Java 插件奉献实际

本文首发

http://www.itmuch.com/skywalk…

本文由博客一文多发平台 OpenWrite 公布！

退出移动版