--- doc/tutorial.md | 257 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 203 insertions(+), 54 deletions(-)
diff --git a/doc/tutorial.md b/doc/tutorial.md index 03f1342..aea6cc2 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -5,7 +5,7 @@
### 概念
-Compass-CI 是一个可持续集成的软件平台。为开发者提供针对上游开源软件（来自 Github, Gitee, Gitlab 等托管平台）的测试服务、登录服务、故障辅助定界服务和基于历史数据的分析服务。通过 Compass-CI，社区开发者可以将开源软件快速引入 openEuler 社区，并补充更多的测试用例，共同构建一个开放、完整的开源软件生态系统。 +Compass-CI 是一个可持续集成的软件平台。为开发者提供针对上游开源软件（来自 Github,Gitee,Gitlab 等托管平台）的测试服务、登录服务、故障辅助定界服务和基于历史数据的分析服务。通过Compass-CI，社区开发者可以将开源软件快速引入openEuler社区，并补充更多的测试用例，共同构建一个开放、完整的开源软件生态系统。
### 功能描述 @@ -30,7 +30,7 @@ Compass-CI 是一个可持续集成的软件平台。为开发者提供针对上
- 聚合开发者测试用例 - 开发者向代码托管平台提交代码、测试用例、测试工具时，Compass-CI 自动获取提交的代码开展构建测试，同时获取开发者编写到开源软件包的测试用例进行自动化测试，并反馈测试结果。 + 开发者向代码托管平台提交代码、测试用例、测试工具时，Compass-CI自动获取提交的代码开展构建测试，同时获取开发者编写到开源软件包的测试用例进行自动化测试，并反馈测试结果。
- 登录环境随时调测
@@ -46,28 +46,59 @@ Compass-CI 是一个可持续集成的软件平台。为开发者提供针对上
-## 使用 Compass-CI -> 当您注册之后，便可以编写 yaml 文件并通过我们的工具上传任务以进行自定义测试，测试功能将尽快上线。 +## 使用Compass-CI
+### 前提条件 + + +- 申请账号 + + 您可以通过向**compass-ci@139.com**发送邮件进行账号申请，邮件标题为"**apply account**"，在正文中提供**您向开源项目提交过的commit的url地址**(我们将根据此进行审查并决定是否发放账号)，并以附件方式添加**准备用来提交任务的个人电脑的公钥**。 + 发送邮件后，将收到一封回复邮件，邮件回复内容如下： + + account_uuird: xxxxxx + SCHED_HOST: ip # 下面配置中将会使用到的ip地址 + SCHED_PORT: port # 下面配置中将会使用到的端口 + +- 构建本地可以提交job的环境 + + - 下载安装[lkp-tests](https://gitee.com/wu_fengguang/lkp-tests) + ```bash + git clone https://gitee.com/wu_fengguang/lkp-tests.git + cd lkp-tests + sudo make install + ``` + + - 配置lab + + - 编辑`.../lkp-tests/include/lab/z9` + ```yaml + SCHED_HOST: ip # 申请账号时回复邮件中的ip + SCHED_PORT: port # 申请账号时回复邮件中的端口 + ``` + - 新建`$HOME/.config/compass-ci/defaults/$USER.yaml` 内容如下 + ```yaml + lab: z9 + ```
- 注册自己的仓库
- 如果您想在 `git push` 的时候, 自动触发测试, 那么需要把您的公开 git url 添加到如下仓库 [upstream-repos](https://gitee.com/wu_fengguang/upstream-repos)%E3%80%82 + 如果您想在 `git push` 的时候, 自动触发测试, 那么需要把您的公开 git url 添加到如下仓库[upstream-repos](https://gitee.com/wu_fengguang/upstream-repos)%E3%80%82 ```bash git clone https://gitee.com/wu_fengguang/upstream-repos.git less upstream-repos/README.md ```
-### 编写 job yaml 文件 +### 编写job yaml文件
-#### job yaml 简介 -job yaml 是测试描述和执行的基本单元，以[YAML](http://yaml.org/YAML_for_ruby.html)%E7%9A%84%E6%A0%BC%E5%BC%8F%E7%BC%96%E5%8... job 文件位于```$LKP_SRC/jobs```路径下。[$LKP_SRC](https://gitee.com/wu_fengguang/lkp-tests) +#### job yaml简介 +job yaml 是测试描述和执行的基本单元，以[YAML](http://yaml.org/YAML_for_ruby.html)%E7%9A%84%E6%A0%BC%E5%BC%8F%E7%BC%96%E5%8... job 文件位于```$LKP_SRC/jobs```路径下。
-#### job yaml 的结构 +#### job yaml的结构 - 标识头部 Header（必选）
- 每一个 job 文件的开始部分，都有一些基础的描述信息，称之为 yaml 的 Header。头部主要有 suite 和 category，suite 是测试套的名称。category 是测试类型，包括 benchmarch（性能测试）/functional（功能测试）/noise-benchmark（不常用）。 + 每一个job文件的开始部分，都有一些基础的描述信息，称之为yaml的Header。头部主要有suite和category，suite是测试套的名称。category是测试类型，包括benchmarch（性能测试）/functional（功能测试）/noise-benchmark（不常用）。 ```yaml suite: netperf \测试套名称 @@ -76,7 +107,7 @@ job yaml 是测试描述和执行的基本单元，以[YAML](http://yaml.org/YAM - 测试脚本和参数（必选）
- - 测试脚本位于```$LKP_SRC/tests```，```$LKP_SRC/daemon```路径下。job yaml 中写入与上述路径中脚本相匹配的文件，将其视为可执行脚本。 + - 测试脚本位于```$LKP_SRC/tests```，```$LKP_SRC/daemon```路径下。job yaml中写入与上述路径中脚本相匹配的文件，将其视为可执行脚本。 ``` $LKP_SRC/setup @@ -101,7 +132,7 @@ job yaml 是测试描述和执行的基本单元，以[YAML](http://yaml.org/YAM
SUT/schduler/部署等资源相关变量。 ```yaml - testbox: vm-2p8g + testbox: vm-hi1620-2p8g os: openeuler os_version: 20.03 os_arch: aarch64 @@ -129,52 +160,170 @@ job yaml 是测试描述和执行的基本单元，以[YAML](http://yaml.org/YAM nterval: 5 ```
-**了解更多 job yaml 相关知识** [Job definition to execution](https://gitee.com/wu_fengguang/lkp-tests/blob/master/jobs/README.md) +**了解更多job yaml相关知识** [Job definition to execution](https://gitee.com/wu_fengguang/lkp-tests/blob/master/jobs/README.md)
### 提交测试任务
+ +使用```submit```关键字提交测试任务，以netperf为例，命令如下。 +```bash +submit netperf.yaml +``` + + +submit命令更多参数设置方法如下。 +``` +- Usage: submit [options] jobs... + submit test jobs to scheduler +- options: + - s, --set 'KEY: VALUE' #add YAML hash to job + - o, --output DIR #save job yaml to DIR + - a, --auto-define-files #auto add define_files + - c, --connect #auto connect to the host + - m, --monitor # monitor job status: use -m 'KEY: VALUE' to add rule" +``` + + ### 查看测试结果
+ +- 生成与存储测试结果 + 测试执行机完成测试任务后，将结果保存到日志文件中，并上传至服务器，按照```$suite/$tbox_group/$date/job_id```的目录结构存储在本地```/srv/result```目录。 + extract-stats 服务将提取本地日志文件中的数据，生成与日志文件对应的json文件，并将汇总后的结果存储到obs数据库(ES)对应id的job中。 + + +- web页面查看结果: + - 点击链接查看obs数据库（ES）中的结果：https://compass-ci.openeuler.org/jobs + + - 点击链接查看文件中的结果,示例：http://124.90.34.227:11300/result/iperf/dc-2g--xiao/2020-09-21/crystal.83385... 文件分为两类： + + - 由测试执行机上传的日志文件： + boot-time, diskstats.gz, interrupts.gz, ...等。 + + - 由extract-stats服务生成的json文件： + boot-time.json, diskstats.json, interrupts.json,stats.json, ... 等。 + json 文件对应每一个日志文件提取后的结果，stats.json为汇总后的结果。 + + ### 比较测试结果
-### 提交 borrow 任务 +测试完成后，Compass-CI通过条件查询数据并将数据合并为多个矩阵，计算每个矩阵的平均值和标准差，以比较测试用例在特定维度的性能变化。最后，将比较结果打印输出。 + + +可以通过如下两种方式比较测试结果： + +- 通过compare web比较 + Compass CI/compare + +- 通过命令行比较 + ``` + compare conditions -d dimension + ``` + +示例比较测试结果如下。 +``` + os=openeuler/os_arch=aarch64/tbox_group=vm-hi1620-2p8g + + + 20 1 metric + -------------------- ------------------------------ ------------------------------ + fails:runs change fails:runs + | | | + 8:21 -38.1% 0:1 last_state.daemon.sshd.exit_code.1 + 1:21 -4.8% 0:1 last_state.daemon.sshd.exit_code.2 + 1:21 -4.8% 0:1 last_state.setup.disk.exit_code.1 + 1:21 -4.8% 0:1 last_state.test.dbench.exit_code.99 + 1:21 -4.8% 0:1 last_state.test.email.exit_code.7 + + + 20 1 metric + -------------------- ------------------------------ ------------------------------ + %stddev change %stddev + \ | \ + 0.02 ± 265% +2259.8% 0.57 mpstat.cpu.all.soft% + 0.48 ± 299% +1334.9% 6.90 mpstat.cpu.all.sys% + 2760.71 ± 164% +292.6% 10838.00 proc-vmstat.nr_dirty_background_threshold + 5522.10 ± 164% +292.6% 21680.00 proc-vmstat.nr_dirty_threshold + +``` + + +### 提交borrow任务 + +borrow任务是指通过提交任务的方式申请环境，提交borrow任务的yaml文件请参考lkp-tests/jobs/borrow-1h.yaml。 + +1. yaml文件配置说明： + + - 必填字段： + ``` + sshd: + pub_key \将用户的公钥信息添加到job中 + email \ 配置用户邮箱地址 + runtime \申请环境的使用时间 h/d/w + testbox \申请环境的规格 + ``` + - 选填字段： + ``` + os \申请环境的操作系统参数 + os_arch + os_version + ``` + +2. 提交任务 + + 执行命令```submit -m -c borrow-1h.yaml```，可以提交borrow任务并自动ssh连接到申请的环境当中。 +
### 提交 bisect 任务
+bisect 任务可以找到首次在git repo中引入问题的commit信息。提交bisect任务的yaml文件请参考 $LKP_SRC/jobs/bisect.yaml。 + +1. yaml文件配置说明： + - 必填字段： + ``` + bisect: + job_id: \提交job的job_id + error_id: \在Compass-CI网页上搜索$job_id，得到$error_ids，从$error_ids中选择一个$error_id。 + ``` +2. 提交任务 + 执行命令```submit bisect.yaml```，提交成功后会收到通知邮件。 + + + ## 高级功能
-### 添加 OS 支持 +### 添加OS支持
-制作一个 initramfs 启动的 cgz 镜像，当系统内核启动时，直接从打包的 cgz 镜像中导出 rootfs，在内存中展开文件系统，利用磁盘的高速缓存机制让系统直接在内存中读写文件，以提升系统的 I/O 性能。 +制作一个initramfs启动的cgz镜像，当系统内核启动时，直接从打包的cgz镜像中导出rootfs，在内存中展开文件系统，利用磁盘的高速缓存机制让系统直接在内存中读写文件，以提升系统的I/O性能。
#### 操作步骤
- 1. 获取对应 os 版本的 rootfs（以 openEuler 为例） - - 通过 docker 获取 rootfs + 1. 获取对应os版本的rootfs（以openEuler为例） + - 通过docker获取rootfs - 1) 下载 openEuler 官方提供的 docker 镜像压缩包 + 1) 下载openEuler官方提供的docker镜像压缩包 ```bash wget https://repo.openeuler.org/openEuler-20.03-LTS/docker_img/aarch64/openEuler-... ``` - 2) 加载 docker 镜像 + 2) 加载docker镜像 ```bash docker load -i openEuler-docker.aarch64 ```
- 3) 启动 openEuler 容器 + 3) 启动openEuler容器 ```bash docker run -id openeuler-20.03-lts ``` - 4) 拷贝 docker 的 rootfs + 4) 拷贝docker的rootfs ```bash docker cp -a docker run -d openeuler-20.03-lts:/ openEuler-rootfs ``` - - 通过 qemu.img(qcow2格式)获取 rootfs (openEuler为例) + - 通过qemu.img(qcow2格式)获取rootfs (以openEuler为例) - 1) 下载 openEule r官方网站提供的 qcow2 格式镜像 + 1) 下载openEuler官方网站提供的qcow2格式镜像 ```bash wget https://repo.openeuler.org/openEuler-20.03-LTS/virtual_machine_img/aarch64/o... ``` @@ -184,22 +333,22 @@ job yaml 是测试描述和执行的基本单元，以[YAML](http://yaml.org/YAM ./run openEuler-20.03-LTS.aarch64.qcow2.xz /tmp/openEuler-rootfs ``` 2. 定制rootfs - 1. 使用chroot命令切换到 rootfs (此步骤需要 root 权限) + 1. 使用chroot命令切换到rootfs中(此步骤需要root权限) ```bash chroot openEuler-rootfs ``` 2. 根据个人需要安装并配置服务
- a. 修改 root 密码 - b. 配置 ssh 服务 + a. 修改root密码 + b. 配置ssh服务 c. 检查系统时间 - d. 如果使用 docker 制作 osimage 还需要以下操作： + d. 如果使用docker制作osimage还需要以下操作： > 1. 安装所需版本内核 - > 2. 从 centos 官方网站下载内核rpm包 - > 3. 使用 yum 进行安装 - > 4. 删除 docker 环境变量文件 + > 2. 从centos官方网站下载内核rpm包 + > 3. 使用yum进行安装 + > 4. 删除docker环境变量文件
- 3. 退出 rootfs，并打包 + 3. 退出rootfs，并打包 ```bash cd $rootfs find . | coip -o -Hnewc |gzip -9 > $os_name.cgz @@ -218,7 +367,7 @@ job yaml 是测试描述和执行的基本单元，以[YAML](http://yaml.org/YAM - 解决方法 1）启动内存不足，增加内存可解决。 - 2）内核文件权限不足，给予 644 权限。 + 2）内核文件权限不足，给予644权限。 2. 系统运行缓慢 @@ -227,7 +376,7 @@ job yaml 是测试描述和执行的基本单元，以[YAML](http://yaml.org/YAM 打包镜像体积过大，会消耗很大内存 - 解决方法
- 建议用户根据具体需要对 rootfs 进行裁剪。 + 建议用户根据具体需要对rootfs进行裁剪。
### 添加测试用例 @@ -238,13 +387,13 @@ job yaml 是测试描述和执行的基本单元，以[YAML](http://yaml.org/YAM
1. 概述：
- 使用 PKGBUILD 完成上游项目源代码的编译构建，同一项目可以使用不同 PKGBUILD 完成项目编译构建过程。 - PKGBUILD 相关参考文档：https://wiki.archlinux.org/index.php/PKGBUILD%E3%80%82 + 使用PKGBUILD完成上游项目源代码的编译构建，同一项目可以使用不同PKGBUILD完成项目编译构建过程。 + PKGBUILD相关参考文档：https://wiki.archlinux.org/index.php/PKGBUILD
2. 步骤：
1) 注册仓库 - 如果您想在 git push 的时候, 自动触发测试, 那么需要把您的公开 git url 添加到如下仓库 [upstream-repos](https://gitee.com/wu_fengguang/upstream-repos)%E3%80%82 + 如果您想在git push的时候, 自动触发测试, 那么需要把您的公开git url添加到如下仓库[upstream-repos](https://gitee.com/wu_fengguang/upstream-repos) ```bash git clone https://gitee.com/wu_fengguang/upstream-repos.git less upstream-repos/README.md @@ -254,17 +403,17 @@ job yaml 是测试描述和执行的基本单元，以[YAML](http://yaml.org/YAM 项目代码更新后自动触发构建任务，无需其他操作。
3) 查看结果 - web: https://compass-ci.openeuler.org/jobs%E3%80%82 + web: https://compass-ci.openeuler.org/jobs
4) 备注 - 目前提供 archlinux 下已有 PKGBUILD 项目构建测试，暂不支持自主导入 PKGBUILD 文件。 - PKGBUILD 存放路径： /srv/git/archlinux/*/*/PKGBUILD。 + 目前提供archlinux下已有PKGBUILD项目构建测试，暂不支持自主导入PKGBUILD文件。 + PKGBUILD存放路径： /srv/git/archlinux/*/*/PKGBUILD
### depends
- 依赖包构建 - 流程: 以下默认使用 debian:sid 版本进行,如果使用其他OS跑测试用例，则需要在 lkp-tests/distro/adaptation/ 下将包名以键值对的形式写入对应 OS 的文件中 + 流程: 以下默认使用debian:sid版本进行,如果使用其他OS跑测试用例，则需要在lkp-tests/distro/adaptation/下将包名以键值对的形式写入对应OS的文件中 > 例： `echo 'apache2: httpd' >> lkp-tests/distro/adaptation/openeuler` 1) 在lkp-tests/distro/depends/下新建一个与测试用例同名的文件 @@ -280,40 +429,40 @@ job yaml 是测试描述和执行的基本单元，以[YAML](http://yaml.org/YAM
-### 本地搭建 compass-ci 服务器节点 +### 本地搭建compass-ci 服务器节点
-在 openEuler 系统一键部署 compass-ci 环境，当前已支持 openEuler-aarch64-20.03-LTS 系统环境，以下配置仅供参考。 +在openEuler系统一键部署compass-ci环境，当前已支持 openEuler-aarch64-20.03-LTS 系统环境，以下配置仅供参考。
#### 准备工作 - 硬件 - 服务器类型：ThaiShan200-2280 (建议) - 架构：aarch64 - 内存：>= 8GB - CPU：64 nuclear (建议) + 服务器类型：ThaiShan200-2280 (建议) + 架构：aarch64 + 内存：>= 8GB + CPU：64 nuclear (建议) 硬盘：>= 500G
- 软件 - OS：openEuler-aarch64-20.03 LTS - git：2.23.0版本 (建议) - 预留空间：>= 300G + OS：openEuler-aarch64-20.03 LTS + git：2.23.0版本 (建议) + 预留空间：>= 300G 网络：可以访问互联网 >**说明：** - >openEuler 系统安装详细操作请参考[添加测试用例](https://openeuler.org/zh/docs/20.03_LTS/docs/Installation/%E5%AE%89%E8%A3%85...) + >openEuler系统安装详细操作请参考[添加测试用例](https://openeuler.org/zh/docs/20.03_LTS/docs/Installation/%E5%AE%89%E8%A3%85...)
#### 操作指导 -1. 登录 openEuler 系统 +1. 登录openEuler系统
2. 创建工作目录并设置文件权限 ```bash mkdir demo && cd demo && umask 002 ``` -3. 克隆 compass-ci 项目代码到 demo 目录 +3. 克隆compass-ci项目代码到demo目录 ```bash git clone https://gitee.com/wu_fengguang/compass-ci.git ``` -4. 执行一键部署脚本 install-tiny +4. 执行一键部署脚本install-tiny ```bash cd compass-ci/sparrow && ./install-tiny ```