开源项目的火热程度取决于技术创新和行业发展趋势，有很多风口浪尖的开源项目 确实非常吸引人。GitHub中的开源项目质量好不好，是不是数项目获得的星星就够 了？该如何洞察开源项目的社区参与程度？如何判断项目核心开发团队的研发效能？ 为了回答这些颇具深度的问题，我们还需要对项目进行更深度的分析。
本教程教你使用Elastic Stack构建GitHub开源项目的关键指标的分析看板，在 Kibana中详细分析项目的几个重要维度。
1. 学习目标
- 1）使用zip/tar.gz软件包在本地轻松搭建Elastic Stack开发环境；
- 2）使用 Filebeat 的 HTTP JSON inputedit 插件从 GitHub API 下载分析数据；
- 3）在Kibana中查询和分析项目数据，图形化展示分析结果；
- 4）掌握Kibana数据分析展示看板的基本操作。
2. 准备工作
首先需要在你的电脑上，进行下面的两项准备工作。你可以使用Windows. macOS 或者Linux操作系统完成本教程的所有操作。
1）在浏览器中打开网址。
https://www.elastic.co/downloads/past-releases#elasticsearch
下载 elasticsearch-7.17.0-darwin-aarch64.tar.gz、kibana-7170-darwin- aarch64.tar.gz、 filebeat-717.0-darwin-x86_64.tar.gz 软件包。
请自行选择正确的平台，以上darwin-aarch64软件包适用于moacOS M1平台； 而darwin-x86_64软件包适用于macOS Intel平台。根据你使用的操作系统，下载 正确的软件包。
2）在GitHub屮创建personal token,用于提升访问GitHub Api请求数限制。
保存这个界面中的类似于这样的个人访问令牌 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 备用。
3. 启动开发环境
1）启动Elasticsearch服务器：下面是在macOS Ml平台上解压缩Elasticsearch 软件包，进入解压后的软件包的目录，使用其可执行文件启动服务。
tar zxvf elasticsearch-7.17.0-darwin-aarch64.tar.gz cd elasticsearch-7.17.0/bin ./elasticsearch -Enode.name=mac-m1
以上使用的命令是直接运行Elasticsearch可执行文件，./elasticsearch - Enode.name=mac-m1，其中参数-Enode.name=mac-m1设定了当前节点的名称， 你也可以使用你的主机名。
如果是在Windows平台上，使用解压缩软件将zip软件包解压后，打开Windows 操作系统的命令行工具，进入解压后的目录中，执行./elasticsearch.exe- Enode.name=mac-m1即可，对于下面的Kibana和Filebeat也是如法炮制。
使用下面的命令启动Kibana服务器。
tar zxvf kibana-7.17.0-darwin-aarch64.tar.gz cd kibana-7.17.0-darwin-aarch64/bin ./kibana
这样就启动了 Kibana服务器，如果你使用的是远程的虚拟机或者云主机，需要在 启动命令中加入一个参数即可，./kibana server -H 0.0.0.0,这样Kibana就可以从 远程的任意Ip地址访问。
Kibana默认会连接上一步所启动的Elasticsearch服务器，在这个开发环境中，默 认没有启用用户名和密码认证，由于是临时的测试，生产环境中建议启用 Elasticsearch的用户密码认证。
3）准备Filebeat的运行环境：解压缩Filebeat软件包，进入解压后的目录，备份 默认的 filebeat.yml 重命名为 filebeat.yml.bk。
用下面的命令准备好Filebeat的运行环境。
tar zxvf filebeat-7.17.0-darwin-x86_64.tar.gz cd filebeat-7.17.0-darwin-x86_64 mv filebeat.yml filebeat.yml.bk
在浏览器中输入http://localhost:5601，在登陆了 Kibana之后，点击左上角的图 标，打开左侧隐藏菜单，找到 Stack Management->Kibana->Advanced Setting 页 面中的这两个选项。
• 打开“Dark mode”选项，打开暗黑模式界面。
•设置 “Document Explorer or classic view” 选项。关闭默认的 classic 经典视
图模式。
自查点
已经成功的将Elasticsearch和Kibana在本机上，启动并运行正常。可以在浏览器 中访问Kibana的界面。浏览若干重要的功能界面：Discover .Dashboard JDevTools, Stack Management 等。
4. 下载示例配置文件
为了降低学习Kibana数据看板的搭建门槛，请访问网址下载准备好的示例文件： https://github.com/martinliu/sdp-dashboard/archive/refs/heads/main.zip
解压下载后的zip文件，其中的三个文件会被使用到：
1) filebeat.yml:完整的Filebeat配置参数模版。用它替换Filebeat的默认配置文 件。本示例配置文件分析的是Ansible的awx项目(Ansbile Tower的开源版 本)你也可以根据需要其替换为其它需要探索的项目；
2) add_gh_fields.json: GitHub项目属性扩展字段定义。将其放入Filebeat程序 文件夹的目录中；
3) export-vl.O.ndjson: Kibana可视化数据分析看板模版。后续将其导入到新安 装的Kibana中。
以上三个文件适用于任何操作系统。如果你的操作系统中安装了 Git客户端，你可 以直接clone这些示例文件所在项目到本地git clone https://github.com/martinliu/sdp-dashboard.git
5. 使用 Filebeat 下载项目数据
Filebeat包含多种数据摄入模块：
各种模块已经覆盖很多类型的数据源，灵活使用这些模块，就可以将Filebeat当作 —个mini版的Logstash使用，当然Logstash包含了更丰富的摄入模块和数据处 理能力。本教程聚焦在“HTTP JSON”采集模块的应用。
6. 获取开源项目概要信息
本教程提供的示例配置文件，采集的是awx的项目数据。将下载示例配置文件中的 add_gh_fields.json 和 filebeat.yml 复制至U Filebeat 的目录中。
使用微软的Virtual Studio Code编辑器【或者其他的纯文本编辑器】打开 filebeat.yml 示例文件。
查看该示例文件，你需要删除掉此文件中间的大部分内容「或者注释掉这部分先不 用的代码」只留下下面的剩余部分，用于做Filebeat的初始化测试。你还需要使用 上面的步骤中所准备好的GitHub Personal Access Token替换配置文件中第21行 中token后面对应的参数。
###################### Filebeat Configuration Example ######################### # ============================== Filebeat inputs =============================== filebeat.inputs: # ============================== 建议先获取这一部分的数据 =============================== # overall, contributors, releases, languages, tags 的数据少且重要，可以手工确认之后在做第二 部分 # 获取项目的概要信息 - overall # GET /repos/{owner}/{repo} - type: httpjson interval: 120m config_version: 2 request.url: https://api.github.com/repos/ansible/awx request.method: GET # 在请求中增加个人认证令牌，提高数据获取条数限制 request.transforms: - set: target: header.Authorization value: 'token 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' # 使用数据处理器，修整数据 processors: # 优化分析：增加方便搜索分析的字段 - add_fields: fields: project: awx kpi: overall # 解码裸 json 结果：将 message 字段中的 json 内容解码为多个字段 - decode_json_fields: fields: ["message"] target: "json" # ======================= Elasticsearch template setting ======================= # 配置索引模版基础属性 setup.template.overwrite: true setup.template.settings: index.number_of_shards: 1 number_of_replicas: 0 index.mapping.total_fields.limit: 5000 setup.template.name: "filebeat" setup.template.pattern: "filebeat-*" setup.template.fields: "fields.yml" # 修改部分 json 字段默认的数据类型 setup.template.json.enabled: true setup.template.json.path: "add_gh_fields.json" setup.template.json.name: "add_gh_fields" # 禁用 ilm 功能 setup.ilm.enabled: false # ================================== General =================================== name: github-crawler # ================================== Outputs =================================== # ---------------------------- Elasticsearch Output ---------------------------- output.elasticsearch: hosts: ["localhost:9200"] index: "filebeat-7" # ================================= Processors ================================= # 删除 Filebeeat 采集到的无关数据，节省存储空间 processors: - drop_fields: fields: ["ecs", "agent", "input", "host", "message"] # ================================== Logging =================================== logging.level: debug # ============================= X-Pack Monitoring ============================== # monitoring.enabled: true
以上配置文件仅使用了必要的参数选项，目的是实现开源项目概要参数信息的抓取，
并测试 Filebeat 的可用性（filebeat-7.17.0-darwin-x86_64.tar.gz 可以正常运行在
macOS M1 平台，Filebeat 目前还没有 aarch64 的软件包）。
不论是 macOS，Windows 还是 Linux，打开命令行工具，进入 Filebeat 的解压缩
目录后，执行下面的测试命令./filebeat test output。
➜ filebeat-7.17.0-darwin-x86_64 ./filebeat test output elasticsearch: http://localhost:9200... parse url... OK connection... parse host... OK dns lookup... OK addresses: ::1, 127.0.0.1 dial up... OK TLS... WARN secure connection disabled talk to server... OK version: 7.17.0
以上返回结果表明：Filebeat可以正常连接本机的Elasticsearch服务器。在Window 操作系统中，需要将filebeat可执行文件名换成filebeat.exe,后面的命令行参数不 变。如果filebeat.yml配置文件的语法错误，这个命令中会报错。
7. 理解 GitHub API 的限流和限速
使用Filebeat作为客户端访问GitHub API需要了解的重要信息都在官方文档上：点 这里，下面都是一些必须理解的知识，以及有必要在运行Filebeat的操作系统上做 的测试。
• 认证用户每小时的请求发送总配额是5000次；对于比较流行的项目而言，issue 或pull request两类的数据量比较多，很可能会用尽配额，建议使用since参数 先拉取近期的数据分析，然后逐步拉取旧数据；
• 企业版用户的配额高一些，每个用户，每小时的配额是15000次；
• 建议在采集数据之前，先在GitHub上对目标项目进行大概的了解，预估overall， contributors，releases，languages，tags，issues 和 pull request 等数据的 条数和可能需要的请求次数，然后分步骤采集各类数据；
• 可以用加大page size参数【per_page参数的最大值为100］的方式降低需要 发出的请求次数。page size越小，采集的项目数据量越大，越可能碰到被限流 的情况。
检查你的PAT是否正确，或者用户是否被限流的方法是，在命令行里运行这条命令
curl-u martinliu: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-I https://api.github.com/users/octocat
这个命令中-umartinliu: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 包含了用户名和个人访问令牌（PAT）。
➜ curl -u martinliu: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 -I https://api.github.com/users/octocat HTTP/2 200 server: GitHub.com date: Thu, 17 Mar 2022 11:01:02 GMT content-type: application/json; charset=utf-8 content-length: 1335 cache-control: private, max-age=60, s-maxage=60 vary: Accept, Authorization, Cookie, X-GitHub-OTP etag: "c9c3cea653b1e722852a41f65a43a5e969c0722c81525b3f1a27f7678269c6ba" last-modified: Tue, 22 Feb 2022 15:07:13 GMT x-oauth-scopes: public_repo, repo:status x-accepted-oauth-scopes: github-authentication-token-expiration: 2022-04-15 06:47:45 UTC x-github-media-type: github.v3; format=json x-ratelimit-limit: 5000 x-ratelimit-remaining: 4440 x-ratelimit-reset: 1647516784 x-ratelimit-used: 560 x-ratelimit-resource: core access-control-expose-headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimitLimit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, XOAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHubSSO, X-GitHub-Request-Id, Deprecation, Sunset access-control-allow-origin: * strict-transport-security: max-age=31536000; includeSubdomains; preload x-frame-options: deny x-content-type-options: nosniff x-xss-protection: 0 referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin content-security-policy: default-src 'none' vary: Accept-Encoding, Accept, X-Requested-With x-github-request-id: 4664:4A3B:121A47C:12EB215:623314EE
以上结果表明了，认证成功的GitHub账号，且未被限流的桩体，结果中的这几个参 数最重要：
* x-ratelimit-limit: 是 5000 表明用户名和 PAT 是正确的，如果是 60 表明，这个用户名和 token 组合错误，未认证用户的限制是 60。 * x-ratelimit-remaining: 4440 当前这个小时里的剩余 API 请求数。 * x-ratelimit-reset: 1647516784 下一次访问限制被重置的时间。
在采集数据之前，确认能看到类似于以上的数据，否则不要继续做下面的步骤。基于GitHub API使用的限流特性，建议分类，分时段采集数据，避免发生被限流的状况。
在使用Filebeat的HTTP JSON模块采集GitHub API数据的过程中很难不会碰到被 限流的情况（请求）在被限流的时候，你可以在filebeat的滚动日志中看到类似下面的信息。
2022-03-17T11:22:53.262+0800 ERROR [input.httpjson-stateless] v2/input.go:115 Error while processing http request: failed to execute http client.Do: server responded with status code 403: {''message'':''Resource protected by organization SAML enforcement. You must grant your Personal Access token access to this organization.'',''documentation_url'': "https://docs.github.com/articles/authenticating -to-a-github-organization-with-saml-single-sign-on/"） {"id": "BF2B0C218CAC3BA0", "input_url": "https://api. github.com/repos/elastic/beats/releases"）
以上信息表明，你当前的账户访问被限流了，这样你不得不等待一个小时后，在让 Filebeat继续采集数据。
自查点
你已经理解了 GitHub API访问流控的基本知识。完成了在正式采集数据前的必要测 试，已经确认当前用户名和PAT是正确无误。在浏览器中提前测试filebeat.yml配 置文件中的request.rul，确保URL可以正常返回结果。
可选的测试：在操作系统上用git clone的方式下载一个自己的项目，修改某个文件 后，将更新push回去，确保和GitHub网站的服务是正常的。
下一步开始进行数据初始化前的准备基础准备工作。
8. 采集并确认部分项目数据
在导入数据之前，需要完成下面这几项任务：
下面详细讲解操作过程。
在解压缩后的zip文件中，找到export-vl.O.ndjson文件；在浏览器中打开Kibana 的界面，点击左侧菜单：需要导入示例Kibana可视化对象。
点击展开左侧菜单，选择：Management->Stack Management->Kibana->Saved Objects-〉点击右上角的"Import”按钮，选中"export-vl.O.ndjson”文件，点击 右下角的导入按钮。
用文本编辑器打开filebeat.yml配置文件，确保在filebeat.inputs:这个部分中只 包含下面的采集项目概况的代码。
- type: httpjson interval: 6m config_version: 2 request.url: https://api.github.com/repos/ansible/awx request.method: GET # 在请求中增加个人认证令牌，提高数据获取条数限制 request.transforms: - set: target: header.Authorization value: 'token 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' #此处的 token 示例 需要被替换 # 使用数据处理器，修整数据 processors: # 优化分析：增加方便搜索分析的字段 - add_fields: fields: project: awx kpi: overall # 解码裸 json 结果：json 内容解码为多个字段 - decode_json_fields: fields: ["message"] target: "json"
以上代码中token后面的字符串需要替换为你自己的，获取方式参考前文。
重点解释几个参数：
• Type: httpjson:这是使用Filebeat的httpjson采集模块，下面整段都是它的 配置，每一段采集一个不同的GitHub API;
• intervel: 6m:配置这个采集条目的采集频率，如果该类型数据变化频率不高， 每天采集两三次即可。60m是60分钟采集一次的频率，可以配置为60分钟的 n倍，GitHub API限流的周期也是按60分钟恢复一次的。
数据量大的时候需要考虑延长采集间隔，取保一个周期内，可以将所有数据都 刷新一遍；
• request.url:这里配置的是不同GitHub API的路径，其中包括了目标分析代码 库的全路径，需要在采集前用浏览器测试其正确性。如果考虑到采集可能受限 制，可以查阅API文档，适当提高page size的大小，从而节省采集请求次数；
• request.transforms:配置了使用token认证方式，保证filebeat使用你的个 人访问令牌，以认证用户的身份采集数据，否则非认证用户60次的请求限制， 分分钟就会被用完；
-add_fields:这一段配置了开源项目的名称和数据分类；这里使用了手工配置 的方式，在后续增加其它类型数据采集的时候，你需要确认修改project:字段 的项目名称，分类名称和request.url对应，不需要修改。
打开命令行工具，进入Filebeat解压缩后的目录中。运行下面的命令
➜ filebeat-7.17.0-darwin-x86_64 ./filebeat -e
这条命令的输出日志应该很快就会停止。按ctrl+c结束首次数据采集测试。在没有 报错的情况下，初始化信息采集就成功了。下面开始在Kibana里确认数据采集结果。
点击Kibana左侧菜单：选择：Analytics->Discovery->右上角的Open菜单-〉选择 overall预制查询视图。在数据显示视图中，至少应该有一条数据，打开这条数据观 察所有采集到的字段。项目Overall的数据信息丰富，变化率不大，可以每天两三 次，就能够绘制出相关的趋势分析图表。
虽然只采集到有限的项目概况数据，现在已经可以查看GitHub开源项目分析看板的样貌了。
点击 Kibana 左侧菜单：选择：Analytics->Dashboard->点击 GitHub Project Analysis。
查看相关信息点:
1）在项目选择菜单中，选中filebeat.yml文件中所配置的项目名称。界面中的数 据会自动刷新；
2）在overall mertrics这个区域里显示了基础的项目数据；
3）这里显示了项目的年龄。这是个扩展字段，如果没有显示正确数值的话，应该 排查解决后，在进行后续的采集和分析。
在我们分析一个开源项目的时候,完全不能只看overall metrics中的概况基础数据。 可以参考DORA 2019 Report的分析报告，点击那个链接打开相关的说明文档。这 是一个长期的跟踪调查，从四个维度分析软件交付效能。我将每个分析维度和 GitHub中的相关开发活动数据做了对应。
在项目分析数据集看板的不同模块的标题中，我使用到了 T1. T2和S1的标签，其 它周围的数据分析块也同时起到了参考支撑作用。
值得说明的是，这四个维度的正向和反向分析都是值得推敲的，可以会推导出完全 相反的结论，需要理性判断。例如：某个代码库长期以来，保持着很高的open issues 的状态，open issue的数量高达1500以上。这个数据可能的分析方向如下：
• 它是非常火爆的项目：遭到用户热捧，参与者积极踊跃的参与项目反馈；
• 项目技术债的坑很深：用户对这个坑很多，坑很深的项目，保持着忍耐且不离 不弃，并长期吐槽的状态；
• 项目核心开发团队（含外部贡献者）专注于创新：项目参与各方无法协同平衡 新功能开发和技术债清理之间的矛盾，而开发新功能的诱惑往往更大，大家就 默认选择了前者；
• 项目的原作者/公司转战其它赛道：项目原作者团队是持续性的主要负责方，解 铃还须系铃人，外部贡献者和其它开发者很难接盘或者挽救这样的项目。
希望以上各种假设开阔了你分析开源项目的思路，而应该选择那个分析结论，还依 赖于你对这个项目其它背景信息，和历史发展过程的了解程度。
可以在Kibana的时间选择控件中，选择最近三个月、半年、一年等时段进行特定 的分析，也可以选择过去的某一年或者半年做YOY的年度对比分析。特别是对 release、pr和issues三类数据的综合分析，我们不难从开发效能的角度度量这些 开源项目的整体研发效能实力。
本教程为大家抓取和分析数据提供了技术工具的支撑。为你进行项目的深度分析提 供基础的信息和角度。根据不同的项目分析需求，我们从这些数据中还可以开发出 其它各种分析角度和图表。我为此在GitHub上也创建了一个项目，欢迎大家一起交流。
项目地址：https://github.com/martinliu/sdp-dashboard
在进入大批量数据采集前，还需要微调Elasticsearch后台的索引字段数量上限。点 击展开左侧菜单，选择：Management->Dev Tools->Console0在这个开发者工具 的左侧输入并执行下面的代码。
PUT filebeat-7/_settings { "index.mapping.total_fields.limit": 5000 }
执行的结果如下图所示。
操作步骤：
自查点
检查确认：
3）完成了 Elasticsearch的索引初始化和配置微调；
4）成功导入了项目概要overall数据，并且在Dashboard上可见这些数据。
在以上自测点都成功以后，再进入下面的步骤。
更多精彩内容，欢迎观看：
《Elastic（中国）产品应用实战》——七、使用Elastic Stack洞察GitHub开源项目的开发效能（下）：https://developer.aliyun.com/article/1220912?spm=a2c6h.13148508.setting.14.653f4f0e1XsCJH
