Apache SkyWalking – Development

Zh: SkyWalking的远程调试

Thu, 24 Jan 2019 00:00:00 +0000

ps:本文仅写给菜鸟，以及不知道如何远程调试的程序员，并且仅仅适用skywalking的远程调试

概述

远程调试的目的是为了解决代码或者说程序包部署在服务器上运行，只能通过log来查看问题，以及不能跟在本地IDE运行debug那样查找问题，观看程序运行流程… 想想当你的程序运行在服务器上，你在本地的IDE随时debug，是不是很爽的感觉。

好了不废话，切入正题。

环境篇

IDE：推荐 IntelliJ IDEA

开发语言: 本文仅限于java，其他语言请自行询问google爸爸或者baidu娘娘

源代码：自行从github下载，并且确保你运行的skywalking包也源代码的一致，（也就是说你自己从源代码编译打包运行，虽然不一样也可以调试，但是你想想你在本地开发，更改完代码，没有重新运行，debug出现的诡异情况）

场景篇

假定有如下三台机器

IP	用途	备注
10.193.78.1	oap-server	skywalking 的oap服务（或者说collector所在的服务器）
10.193.78.2	agent	skywalking agent运行所在的服务器
10.193.78.0	IDE	你自己装IDE也就是IntelliJ IDEA的机器

以上环境，场景请自行安装好，并确认正常运行。本文不在赘述

废话终于说完了

操作篇

首要条件，下载源码后，先用maven 打包编译。然后使用Idea打开源码的父目录，整体结构大致如下图

1 :agent调试

1)Idea 配置部分

点击Edit Configurations 在弹出窗口中依次找到（红色线框的部分）并点击打开的界面如下

修改Name值，自己随意，好记即可然后Host输入10.193.78.2 Port默认或者其他的，重要的是这个端口在10.193.78.2上没有被占用

然后找到Use module classpath 选择 apm-agent 最终的结果如下：

注意选择目标agent运行的jdk版本，很重要

然后点击Apply，并找到如下内容，并且复制待用

2）agent配置部分

找到agent配置的脚本，并打开，找到配置agent的地方，就这个地方，在这个后边加上刚才复制的内容最终的结果如下提供一个我配置的weblogic的配置（仅供参考）然后重启应用（agent）

3）调试

回到Idea中找到这个地方，并点击debug按钮，你没看错，就是红色圈住的地方然后控制台如果出现以下字样：那么恭喜你，可以愉快的加断点调试了。 ps:需要注意的是agent的、 service instance的注册可能不能那么愉快的调试。因为这个注册比较快，而且是在agent启动的时候就发生的，而远程调试也需要agent打开后才可以调试，所以，如果你手快当我没说这句话。

2 :oap-server的调试（也就是collector的调试）

具体过程不在赘述，和上一步的agent调试大同小异，不同的是 Use module classpath需要选择oap-server

Zh: SkyWalking Java 插件贡献实践

Mon, 21 Jan 2019 00:00:00 +0000

引言

《SkyWalking Java 插件贡献实践》：本文将基于SkyWalking 6.0.0-GA-SNAPSHOT版本，以编写Redis客户端Lettuce的SkyWalking Java Agent 插件为例，与大家分享我贡献PR的过程，希望对大家了解SkyWalking Java Agent插件有所帮助。

基础概念

OpenTracing和SkyWalking链路模块几个很重要的语义概念。

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组成。

核心API

跨进程ContextCarrier核心API

为了实现分布式跟踪，需要绑定跨进程的跟踪，并且应该传播上下文整个过程。这就是ContextCarrier的职责。
以下是实现有关跨进程传播的步骤：
- 在客户端，创建一个新的空的ContextCarrier，将ContextCarrier所有信息放到HTTP heads、Dubbo attachments 或者Kafka messages。
- 通过服务调用，将ContextCarrier传递到服务端。
- 在服务端，在对应组件的heads、attachments或messages获取ContextCarrier所有消息。将服务端和客户端的链路信息绑定。

跨线程ContextSnapshot核心API

除了跨进程，跨线程也是需要支持的，例如异步线程（内存中的消息队列）和批处理在Java中很常见，跨进程和跨线程十分相似，因为都是需要传播上下文。唯一的区别是，不需要跨线程序列化。
以下是实现有关跨线程传播的步骤：
- 使用ContextManager＃capture获取ContextSnapshot对象。
- 让子线程以任何方式，通过方法参数或由现有参数携带来访问ContextSnapshot。
- 在子线程中使用ContextManager#continued。

详尽的核心API相关知识，可点击阅读《插件开发指南-中文版本》

插件实践

Lettuce操作redis代码

@PostMapping("/ping")
public String ping(HttpServletRequest request) throws ExecutionException, InterruptedException {
    RedisClient redisClient = RedisClient.create("redis://" + "127.0.0.1" + ":6379");
    StatefulRedisConnection<String, String> connection0 = redisClient.connect();
    RedisAsyncCommands<String, String> asyncCommands0 = connection0.async();
    AsyncCommand<String, String, String> future = (AsyncCommand<String, String, String>)asyncCommands0.set("key_a", "value_a");
    future.onComplete(s -> OkHttpClient.call("http://skywalking.apache.org"));
    future.get();
    connection0.close();
    redisClient.shutdown();
    return "pong";
}

插件源码架构

Lettuce对Redis封装与Redisson Redisson 类似，目的均是实现简单易用，且无学习曲线的Java的Redis客户端。所以要是先对Redis操作的拦截，需要学习对应客户端的源码。

设计插件

理解插件实现过程，找到最佳InterceptPoint位置是实现插件融入SkyWalking的核心所在。

代码实现

PR的url：Support lettuce plugin

实践中遇到的问题

多线程编程使用debug断点会将链路变成同步，建议使用run模式增加log，或者远程debug来解决。
多线程编程，需要使用跨线程ContextSnapshot核心API，否则链路会断裂。
CompleteableCommand.onComplete方法有时会同步执行，这个和内部机制有关，有时候不分离线程。
插件编译版本若为1.7+，需要将插件放到可选插件中。因为sniffer支持的版本是1.6。

插件兼容

为了插件得到插件最终的兼容兼容版本，我们需要使用docker对所有插件版本的测试，具体步骤如下：

编写测试用例：关于如何编写测试用例，请按照如何编写文档来实现。
提供自动测试用例。如：Redisson插件testcase
确保本地几个流行的插件版本，在本地运行起来是和自己的预期是一致的。
在提供自动测试用例并在CI中递交测试后，插件提交者会批准您的插件。
最终得到完整的插件测试报告。

Pull Request

提交PR

提交PR的时候，需要简述自己对插件的设计，这样有助于与社区的贡献者讨论完成codereview。

申请自动化测试

测试用例编写完成后，可以申请自动化测试，在自己的PR中会生成插件兼容版本的报告。

插件文档

插件文档需要更新：Supported-list.md相关插件信息的支持。

插件如果为可选插件需要在agent-optional-plugins可选插件文档中增加对应的描述。

注释

Lettuce是一个完全无阻塞的Redis客户端，使用netty构建，提供反应，异步和同步数据访问。了解细节可点击阅读 lettuce.io;

OpenTracing是一个跨编程语言的标准，了解细节可点击阅读《OpenTracing语义标准》;

span:org.apache.skywalking.apm.agent.core.context.trace.AbstractSpan接口定义了所有Span实现需要完成的方法;

Redisson是一个非常易用Java的Redis客户端，它没有学习曲线，无需知道任何Redis命令即可开始使用它。了解细节可点击阅读 redisson.org;

Zh: SkyWalking apm-sniffer 原理学习与插件编写

Fri, 21 Dec 2018 00:00:00 +0000

导读

SkyWalking 中 Java 探针是使用 JavaAgent 的两大字节码操作工具之一的 Byte Buddy（另外是 Javassist）实现的。项目还包含.Net core 和 Nodejs 自动探针，以及 Service Mesh Istio 的监控。总体上，SkyWalking 是一个多语言，多场景的适配，特别为微服务、云原生和基于容器架构设计的可观测性分析平台（Observability Analysis Platform）。
本文基于 SkyWalking 5.0.0-RC2 和 Byte Buddy 1.7.9 版本，会从以下几个章节，让大家掌握 SkyWalking Java 探针的使用，进而让 SkyWalking 在自己公司中的二次开发变得触手可及。
- Byte Buddy 实现 JavaAgent 项目
- 迭代 JavaAgent 项目的方法论
- SkyWalking agent 项目如何 Debug
- SkyWalking 插件开发实践
文章底部有 SkyWalking 和 Byte Buddy 相应的学习资源。

Byte Buddy 实现

首先如果你对 JavaAgent 还不是很了解可以先百度一下，或在公众号内看下《JavaAgent 原理与实践》简单入门下。
SpringMVC 分发请求的关键方法相信已经不用我在赘述了，那我们来编写 Byte Buddy JavaAgent 代码吧。

 public class AgentMain {
    public static void premain(String agentOps, Instrumentation instrumentation) {
        new AgentBuilder.Default()
                .type(ElementMatchers.named("org.springframework.web.servlet.DispatcherServlet"))
                .transform((builder, type, classLoader, module) ->
                        builder.method(ElementMatchers.named("doDispatch"))
                                .intercept(MethodDelegation.to(DoDispatchInterceptor.class)))
                .installOn(instrumentation);
    }
}

编写 DispatcherServlet doDispatch 拦截器代码（是不是跟 AOP 如出一辙）

 public class DoDispatchInterceptor {
    @RuntimeType
    public static Object intercept(@Argument(0) HttpServletRequest request, @SuperCall Callable<?> callable) {
        final StringBuilder in = new StringBuilder();
        if (request.getParameterMap() != null && request.getParameterMap().size() > 0) {
            request.getParameterMap().keySet().forEach(key -> in.append("key=" + key + "_value=" + request.getParameter(key) + ","));
        }
        long agentStart = System.currentTimeMillis();
        try {
            return callable.call();
        } catch (Exception e) {
            System.out.println("Exception :" + e.getMessage());
            return null;
        } finally {
            System.out.println("path:" + request.getRequestURI() + " 入参:" + in + " 耗时:" + (System.currentTimeMillis() - agentStart));
        }
    }
}

resources/META-INF/MANIFEST.MF

Manifest-Version: 1.0
Premain-Class: com.z.test.agent.AgentMain
Can-Redefine-Classes: true

pom.xml 文件

dependencies
    +net.bytebuddy.byte-buddy 
    +javax.servlet.javax.servlet-api *scope=provided
plugins
    +maven-jar-plugin *manifestFile=src/main/resources/META-INF/MANIFEST.MF
    +maven-shade-plugin *include:net.bytebuddy:byte-buddy:jar:
    +maven-compiler-plugin

小结：没几十行代码就完成了，通过 Byte Buddy 实现应用组件 SpringMVC 记录请求路径、入参、执行时间 JavaAgent 项目，是不是觉得自己很优秀。

持续迭代 JavaAgent

本章节主要介绍 JavaAgent 如何 Debug，以及持续集成的方法论。
首先我的 JavaAgent 项目目录结构如图所示:
应用项目是用几行代码实现的 SpringBootWeb 项目:

@SpringBootApplication(scanBasePackages = {"com"})
public class TestBootWeb {
    public static void main(String[] args) {
        SpringApplication.run(TestBootWeb.class, args);
    }
    @RestController
    public class ApiController {
        @PostMapping("/ping")
        public String ping(HttpServletRequest request) {
            return "pong";
        }
    }
}

下面是关键 JavaAgent 项目如何持续迭代与集成:

VM options增加:-JavaAgent:{$HOME}/Code/github/z_my_test/test-agent/target/test-agent-1.0-SNAPSHOT.jar=args
Before launch 在Build之前增加：
    Working directory:{$HOME}/Code/github/incubator-skywalking
    Command line:-T 1C -pl test-agent -am clean package -Denforcer.skip=true -Dmaven.test.skip=true -Dmaven.compile.fork=true

小结：看到这里的将 JavaAgent 持续迭代集成方法，是不是瞬间觉得自己手心已经发痒起来，很想编写一个自己的 agent 项目了呢，等等还有一个好消息:test-demo 这 10 几行的代码实现的 Web 服务，居然有 5k 左右的类可以使用 agent 增强。
注意 mvn 编译加速的命令是 maven3 + 版本以上才支持的哈。

SkyWalking Debug

峰回路转，到了文章的主题《SkyWalking 之高级用法》的正文啦。首先，JavaAgent 项目想 Debug，还需要将 agent 代码与接入 agent 项目至少在同一个工作空间内，网上方法有很多，这里我推荐大家一个最简单的方法。File->New->Module from Exisiting Sources… 引入 skywalking-agent 源码即可
详细的 idea 编辑器配置：
优化 SkyWalking agent 编译时间，我的集成时间优化到 30 秒左右：

VM options增加:-JavaAgent:-JavaAgent:{$HOME}/Code/github/incubator-skywalking/skywalking-agent/skywalking-agent.jar：不要用dist里面的skywalking-agent.jar，具体原因大家可以看看源码：apm-sniffer/apm-agent/pom.xml中的maven插件的使用。
Before launch 在Build之前增加：
    Working directory:{$HOME}/Code/github/incubator-skywalking
    Command line:-T 1C -pl apm-sniffer/apm-sdk-plugin -amd clean package -Denforcer.skip=true -Dmaven.test.skip=true -Dmaven.compile.fork=true： 这里我针对插件包，因为紧接着下文要开发插件
另外根pom注释maven-checkstyle-plugin也可加速编译

kob 之 SkyWalking 插件编写

kob（贝壳分布式作业调度框架）是贝壳找房项目微服务集群中的基础组件，通过编写贝壳分布式作业调度框架的 SkyWalking 插件，可以实时收集作业调度任务的执行链路信息，从而及时得到基础组件的稳定性，了解细节可点击阅读《贝壳分布式调度框架简介》。想详细了解 SkyWalking 插件编写可在文章底部参考链接中，跳转至对应的官方资源，好话不多说，代码一把唆起来。
apm-sdk-plugin pom.xml 增加自己的插件 model

<artifactId>apm-sdk-plugin</artifactId>
    <modules>
        <module>kob-plugin</module>
        ...
    <modules>

resources.skywalking-plugin.def 增加自己的描述

kob=org.apache.skywalking.apm.plugin.kob.KobInstrumentation

在 SkyWalking 的项目中，通过继承 ClassInstanceMethodsEnhancePluginDefine 可以定义需要拦截的类和增强的方法，编写作业调度方法的 instrumentation

public class KobInstrumentation extends ClassInstanceMethodsEnhancePluginDefine {
    private static final String ENHANCE_CLASS = "com.ke.kob.client.spring.core.TaskDispatcher";
    private static final String INTERCEPT_CLASS = "org.apache.skywalking.apm.plugin.kob.KobInterceptor";
    @Override
    protected ClassMatch enhanceClass() {
        return NameMatch.byName(ENHANCE_CLASS);
    }
    @Override
    protected ConstructorInterceptPoint[] getConstructorsInterceptPoints() {
        return null;
    }
    @Override
    protected InstanceMethodsInterceptPoint[] getInstanceMethodsInterceptPoints() {
        return new InstanceMethodsInterceptPoint[] {
                new InstanceMethodsInterceptPoint() {
                    @Override
                    public ElementMatcher<MethodDescription> getMethodsMatcher() {
                        return named("dispatcher1");
                    }
                    @Override
                    public String getMethodsInterceptor() {
                        return INTERCEPT_CLASS;
                    }
                    @Override
                    public boolean isOverrideArgs() {
                        return false;
                    }
                }
        };
    }
}

通过实现 InstanceMethodsAroundInterceptor 后，定义 beforeMethod、afterMethod 和 handleMethodException 的实现方法，可以环绕增强指定目标方法，下面自定义 interceptor 实现 span 的跟踪（这里需要注意 SkyWalking 中 span 的生命周期，在 afterMethod 方法中结束 span）

public class KobInterceptor implements InstanceMethodsAroundInterceptor {
    @Override
    public void beforeMethod(EnhancedInstance objInst, Method method, Object[] allArguments,  Class<?>[] argumentsTypes, MethodInterceptResult result) throws Throwable {
        final ContextCarrier contextCarrier = new ContextCarrier();
        com.ke.kob.client.spring.model.TaskContext context = (TaskContext) allArguments[0];
        CarrierItem next = contextCarrier.items();
        while (next.hasNext()) {
            next = next.next();
            next.setHeadValue(JSON.toJSONString(context.getUserParam()));
        }
        AbstractSpan span = ContextManager.createEntrySpan("client:"+allArguments[1]+",task:"+context.getTaskKey(), contextCarrier);
        span.setComponent(ComponentsDefine.TRANSPORT_CLIENT);
        SpanLayer.asRPCFramework(span);
    }
    @Override
    public Object afterMethod(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes, Object ret) throws Throwable {
        ContextManager.stopSpan();
        return ret;
    }
    @Override
    public void handleMethodException(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes, Throwable t) {
    }
}

实现效果，将操作名改成任务执行节点 + 任务执行方法，实现 kob 的 SkyWalking 的插件编写，加上报警体系，可以进一步增加公司基础组件的稳定性。