Apache SkyWalking – Open Source Contribution

Zh: 暑期 2020 活动学生（张可）心得分享

Sun, 20 Dec 2020 00:00:00 +0000

今年暑假期间我参加了开源软件供应链点亮计划—暑期 2020 的活动，在这个活动中，我主要参加了 Apache SkyWalking 的 Python Agent 的开发，最终项目顺利结项并获得了”最具潜力奖“，今天我想分享一下我参与这个活动以及开源社区的感受与收获。

缘起

其实我在参加暑期 2020 活动之前就听说过 SkyWalking 了。我研究生的主要研究方向是微服务和云原生，组里的学长们之前就在使用 SkyWalking 进行一些研究工作，也是通过他们，我了解到了 OpenTracing, SkyWalking 等与微服务相关的 Tracing 工具以及 APM 等，当时我就在想如果有机会可以深度参加这些开源项目就好了。巧的是，也正是在差不多的时候，本科的一个学长发给了我暑期 2020 活动的链接，我在其中惊喜的发现了 SkyWalking 项目。

虽然说想要参与 SkyWalking 的开发，但是真的有了机会我却有一些不自信——这可是 Star 上万的 Apache 顶级项目。万幸的是在暑期 2020 活动中，每一个社区都提供了很多题目以供选择，想参与的同学可以提前对要做的事情有所了解，并可以提前做一些准备。我当时也仔细地浏览了项目列表，最终决定申请为 Python Agent 支持 Flask 或 Django 埋点的功能。当时主要考虑的是，我对 Python 语言比较熟悉，同时也有使用 Flask 等 web 框架进行开发的经验，我认为应该可以完成项目要求。为了能让心里更有底一些，我阅读了 Python Agent 的源码，写下了对项目需要做的工作的理解，并向项目的导师柯振旭发送了自荐邮件，最终被选中去完成这个项目。

过程

被选中后我很激动，也把这份激动化作了参与开源的动力。我在进一步阅读源码，搭建本地环境后，用了三周左右的时间完成了 Django 项目的埋点插件的开发，毕竟我选择的项目是一个低难度的项目，而我在 Python web 方面也有一些经验。在这之后，我的导师和我进行了沟通，在我表达了想要继续做贡献的意愿之后，他给我建议了一些可以进一步进行贡献的方向，我也就继续参与 Python Agent 的开发。接下来，我陆续完成了 PyMongo 埋点插件, 插件版本检查机制, 支持使用 kafka 协议进行数据上报等功能。在提交了暑期 2020 活动的结项申请书后，我又继续参与了在端到端测试中增加对百分位数的验证等功能。

在整个过程中，我遇到过很多问题，包括对问题认识不够清晰，功能的设计不够完善等等，但是通过与导师的讨论以及 Code Review，这些问题最终都迎刃而解了。此外他还经常会和我交流项目进一步发展方向，并给我以鼓励和肯定，在这里我想特别感谢我的导师在整个项目过程中给我的各种帮助。

收获

参加暑期 2020 的活动带给我了很多收获，主要有以下几点：

第一是让我真正参与到了开源项目中。在之前我只向在项目代码或文档中发现的 typo 发起过一些 Pull Request，但是暑期 2020 活动通过列出项目＋导师指导的方式，明确了所要做的事情，并提供了相应的指导，降低了参与开源的门槛，使得我们学生可以参与到项目的开发中来。

第二是对我的专业研究方向也有很多启发，我的研究方向就是微服务与云原生相关，通过参与到 SkyWalking 的开发中使得我可以更好地理解研究问题中的一些概念，也让我更得心应手得使用 SkyWalking 来解决一些实际的问题。

第三是通过参与 SkyWalking Python Agent 以及其他部分的开发，我的贡献得到了社区的承认，并在最近被邀请作为 Committer 加入了社区，这对我而言是很高的认可，也提升了我的自信心。

第四点就是我通过这个活动认识了不少新朋友，同时也开拓了我的视野，使得我对于开源项目与开源社区有了很多新的认识。

建议

最后同样是我对想要参与开源社区，想要参与此类活动的同学们的一些建议：

虽然奖金很吸引人，但是还是希望大家能抱着长期为项目进行贡献的心态来参与开源项目，以这样的心态参与开源可以让你更好地理解开源社区的运作方式，也可以让你更有机会参与完成激动人心的功能，你在一个东西上付出的时间精力越多，你能收获的往往也越多。
在申请项目的时候，可以提前阅读一下相关功能的源码，并结合自己的思考去写一份清晰明了的 proposal ，这样可以帮助你在申请人中脱颖而出。
在开始着手去完成一个功能之前，首先理清思路，并和自己的导师或了解这一部分的人进行沟通与确认，从而尽量避免在错误的方向上浪费太多时间。

Zh: 暑期2020活动心得分享

Sat, 19 Dec 2020 00:00:00 +0000

背景

我是一个热爱编程、热爱技术的人，⼀直以来都向往着能参与到开源项⽬中锻炼⾃⼰，但当我面对庞大而复杂的项目代码时，却感到手足无措，不知该从何开始。⽽此次的“开源软件供应链点亮计划-暑期2020”活动则正好提供了这样⼀个机会：清晰的任务要求、开源社区成员作为导师提供指导以及一笔丰厚的奖金，让我顺利地踏上了开源这条道路。

回顾

在“暑期2020”活动的这两个多月里，我为 SkyWalking 的命令行工具实现了一个 dashboard，此外在阅读项目源码的过程中，还发现并修复了几个 bug。到活动结束时，我共提交了11个 PR，贡献了两千多行改动，对 SkyWalking CLI 项目的贡献数量排名第二，还获得了“最具潜力奖”。

我觉得之所以能够如此顺利地完成这个项⽬主要有两个原因。一方面，我选择的 SkyWalking CLI 项⽬当时最新的版本号为0.3.0，还处于起步阶段，代码量相对较少，⽽且项⽬结构非常清晰，文档也较为详细，这对于我理解整个项⽬⾮常有帮助，从⽽能够更快地上⼿。另一方面，我的项目导师非常认真负责，每次我遇到问题，导师都会及时地为我解答，然后我提交的 PR 也能够很快地被 review。⽽且导师不时会给予我肯定的评论与⿎励，这极⼤地提⾼了我的成就感，让我更加积极地投⼊到下⼀阶段的⼯作，形成⼀个正向的循环。

收获

回顾整个参与过程，觉得自己收获颇多：

首先，我学习到了很多可能在学校里接触不到的新技术，了解了开源项目是如何进行协作，开源社区是如何运转治理的，以及开源文化、Apache way 等知识，仿佛进入了一个崭新而精彩的世界。

其次，我的编程能力得到了锻炼。因为开源项目对于代码的质量有较高的要求，因此我会在编程时有意识地遵守相关的规范，培养良好的编码习惯。然后在导师的 code review 中也学习到了一些编程技巧。

此外，参与开源为我的科研带来了不少灵感。因为我的研究方向是智能软件工程，旨在将人工智能技术应用在软件工程的各个环节中，这需要我在实践中发现实际问题。而开源则提供了这样一个窗口，让我足不出户即可参与到软件项目的设计、开发、测试和发布等环节。

最后也是本次活动最大的一个收获，我的贡献得到了社区的认可，被提名成为了 SkyWalking 社区的第一位学生 committer。

建议

最后，对于将来想要参加此类活动的同学，附上我的一些建议：

第一，选择活跃、知名的社区。社区对你的影响将是极其深远的，好的社区意味着成熟的协作流程、良好的氛围、严谨的代码规范，以及有更大几率遇到优秀的导师，这些对于你今后在开源方面的发展都是非常有帮助的。

第二，以兴趣为导向来选择项目，同时要敢于走出舒适区。我最初在选择项目时，初步确定了两个，一个是低难度的 Python 项目，另一个是中等难度的 Go 项目。当时我很纠结：因为我对 Python 语言比较熟悉，选择一个低难度的项目是比较稳妥的，但是项目的代码我看的并不是很懂，具体要怎么做我完全没有头绪；而 Go 项目是一个命令行工具，我对这个比较感兴趣，且有一个大致的思路，但是我对 Go 语言并不是很熟悉，实践经验为零。最后凭借清晰具体的 proposal 我成功申请到了 Go 项目并顺利地完成了，还在实践中快速掌握了一门新的编程语言。

这次的“暑期2020”活动虽已圆满结束，但我的开源之路才刚刚开始。

Zh: Apache SkyWalking Committer申请流程

Thu, 12 Sep 2019 00:00:00 +0000

作者： SkyWalking committer，Kdump

本文介绍申请Apache SkyWalking Committer流程, 流程包括以下步骤

与PMC成员表达想成为committer的意愿(主动/被动)
PMC内部投票
PMC正式邮件邀请
填写Apache iCLA申请表
设置ApacheID和邮箱
设置GitHub加入Apache组织
GitHub其它一些不重要设置

前期过程

与PMC成员表达想成为committer的意愿(主动/被动)
PMC内部投票

当你对项目的贡献活跃度足够高或足够多时, Skywalking项目的PMC(项目管理委员会)会找到你并询问你是否有意愿成为项目的Committer, 或者也可以主动联系项目的PMC表达自己的意向, 在此之后PMC们会进行内部讨论和投票并告知你是否可以进入下一个环节.这个过程可能需要一周. 如果PMC主动邀请你进行非正式的意愿咨询, 你可以选择接受或拒绝.

PS:PMC会向你索要你的个人邮箱, 建议提供Gmail, 因为后期绑定Apache邮箱需要用到, 其它邮箱我不确定是否能绑定.

PS:从Apache官方的流程来讲, 现有的PMC会在没有通知候选人的情况下先进行候选人投票, 但是Skywalking项目的PMC有可能更倾向于先得到候选人的意愿再进行投票.

正式阶段

PMC正式邮件邀请
- 当你收到PMC正式的邀请邮件时, 恭喜你, 你已经通过了PMC的内部投票, 你需要用英文回答接受邀请或者拒绝邀请, 记住回复的时候一定要选择全部回复.
填写Apache iCLA申请表
- 在你收到的PMC邮件中, 有几个ASF官方链接需要你去浏览, 重点的内容是查看CLAs, 并填写Individual Contributor License Agreement, 你可以将icla.pdf文件下载到本地, 使用PDF工具填写里面所需的信息, 并打印出来签名(一定要手写签名, 否则会被要求重新签名), 再扫描(或手机拍照)成电子文档(需要回复PDF格式, 文件名建议重命名为你的名字-icla.pdf), 使用gpg对电子文档进行签名(参考[HOW-TO: SUBMITTING LICENSE AGREEMENTS AND GRANTS
  
  ](http://www.apache.org/licenses/contributor-agreements.html#submitting)), Window可以使用GnuPG或者Gpg4win.
- 完成gpg签名后, 请将你签名用的公钥上送到pool.sks-keyservers.net服务器, 并在这个页面中验证你的公钥是否可以被搜索到, 搜索关键词可以是你秘钥中填写的名字或者邮箱地址.
- gpg签名后, 会生成.pdf.asc的文件, 需要将你的你的名字-icla.pdf和你的名字-icla.pdf.asc以附件的方式一起发送到secretary@apache.org, 并抄送给private@skywalking.apache.org.
设置ApacheID和邮箱
- 大概5个工作日内, 你会收到一封来至于root@apache.org的邮件, 主题为Welcome to the Apache Software Foundation (ASF)!, 恭喜你, 你已经获得了ApacheID, 这时候你需要根据邮件内容的提示去设置你的ApacheID密码, 密码设置完成后, 需要在Apache Account Utility页面中重点设置Forwarding email address和Your GitHub Username两个信息.保存信息的时候需要你填写当前的ApacheID的密码.
- 现在进入Gmail, 选择右上角的齿轮->设置->账号和导入->添加其他电子邮件地址->参考Sending email from your apache.org email address给出的信息根据向导填写Apache邮箱.
设置GitHub加入Apache组织
- 进入Welcome to the GitBox Account Linking Utility!, 按照顺序将Apache Account和GitHub Account点绿, 想点绿MFA Status, 需要去GitHub开启2FA, 请参考配置双重身份验证完成2FA的功能.
- 等待1~2小时后登陆自己的GitHub的dashboard界面, 你应该会看到一条Apache组织邀请你加入的通知, 这个时候接受即可享有Skywalking相关GitHub项目权限了.

其它提示

GitHub其它一些不重要设置
- 在GitHub首页展示Apache组织的logo: 进入Apache GitHub组织->People->搜索自己的GitHubID->将Private改成Public

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;