如何在 GitLab CI/CD 中使用 Bencher

根据您的使用案例，您可以在 GitLab CI/CD 中为您的以下项设置持续基准测试：

• 目标分支
• 合并请求

确保在继续之前已创建 API token并将其设置为名为 BENCHER_API_TOKEN 的屏蔽变量！导航到 Your Repo -> Settings -> CI/CD -> Variables -> Expand -> Add variable。变量键应为 BENCHER_API_TOKEN，变量值应为您的 API token。勾选 Protect variable 和 Mask variable 这两个选项。

目标分支

统计连续基准测试 的基石是为目标分支建立历史基线。这个历史基线可以用于检测合并请求中的性能回归。

benchmark_target_branch:
  rules:
    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
      when: always
  image: debian:bullseye
  before_script:
    - curl --proto '=https' --tlsv1.2 -sSfL https://bencher.dev/download/install-cli.sh | sh
  script:
    - |
      bencher run \
      --project project-abc4567-wxyz123456789 \
      --token "$BENCHER_API_TOKEN" \
      --branch main \
      --testbed debian:bullseye \
      --threshold-measure latency \
      --threshold-test t_test \
      --threshold-max-sample-size 64 \
      --threshold-upper-boundary 0.99 \
      --thresholds-reset \
      --err \
      --adapter json \
      bencher mock

1. 创建一个 GitLab CI/CD 文件。 （例如：.gitlab-ci.yml）
2. 创建一个 GitLab CI/CD 作业。 （例如：benchmark_target_branch）
3. 当管道由 main 分支的 push 触发时运行 if。 查看 GitLab CI/CD rules 文档 和 GitLab CI/CD 预定义变量文档 以获取完整概述。 （例如：rules: if: ...）
4. 设置作业运行的 image。 查看 GitLab CI/CD image 文档 以获取完整概述。 （例如：image: debian:bullseye）
5. 使用 便捷脚本 安装 Bencher CLI。 （例如：before_script: ...）
6. 使用 bencher run CLI 子命令运行您的 main 分支基准测试。 查看 the bencher run CLI 子命令 以获取完整概述。 （例如：bencher run）
7. 将 --project 选项设置为项目 slug。 查看 the --project 文档 以获取更多详情。 （例如：--project project-abc4567-wxyz123456789）
8. 将 --token 选项设置为已屏蔽的 BENCHER_API_TOKEN 环境变量。 查看 the --token 文档 以获取更多详情。 （例如：--token "$BENCHER_API_TOKEN"）
9. 将 --branch 选项设置为分支名称。 查看 the --branch 文档 以获取完整概述。 （例如：--branch main）
10. 将 --testbed 选项设置为测试平台名称。 这可能应与在 image 中选择的机器匹配。 查看 the --tested 文档 以获取更多详情。 （例如：--testbed debian:bullseye）
11. 为 main 分支、debian:bullseye 测试平台和 latency 测量设置阈值：
    1. 将 --threshold-measure 选项设置为 bencher mock 生成的内置 latency 测量。 查看 the --threshold-measure 文档 以获取更多详情。 （例如：--threshold-measure latency）
    2. 将 --threshold-test 选项设置为 Student’s t-test (t_test)。 查看 the --threshold-test 文档 以获取完整概述。 （例如：--threshold-test t_test）
    3. 将 --threshold-max-sample-size 选项设置为最大样本大小 64。 查看 the --threshold-max-sample-size 文档 以获取更多详情。 （例如：--threshold-max-sample-size 64）
    4. 将 --threshold-upper-boundary 选项设置为上界 0.99。 查看 the --threshold-upper-boundary 文档 以获取更多详情。 （例如：--threshold-upper-boundary 0.99）
    5. 设置 --thresholds-reset 标志以确保只有指定的阈值处于活动状态。 查看 the --thresholds-reset 文档 以获取完整概述。 （例如：--thresholds-reset）
12. 设置 --err 标志以在生成警报时使命令失败。 查看 the --err 文档 以获取完整概述。 （例如：--err）
13. 将 --adapter 选项设置为 Bencher Metric Format JSON (json)，由 bencher mock 生成。 查看 benchmark harness adapters 以获取完整概述。 （例如：--adapter json）
14. 指定基准测试命令参数。 查看 benchmark command 以获取完整概述。 （例如：bencher mock）

合并请求

为了捕捉合并请求中的性能回归，您需要在MRs上运行您的基准测试。 下面的例子应该仅用于相同存储库内的分支。

benchmark_mr_branch:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: always
  image: debian:bullseye
  before_script:
    - curl --proto '=https' --tlsv1.2 -sSfL https://bencher.dev/download/install-cli.sh | sh
  script:
    - |
      bencher run \
      --project project-abc4567-wxyz123456789 \
      --token "$BENCHER_API_TOKEN" \
      --branch "$CI_COMMIT_REF_NAME" \
      --start-point "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" \
      --start-point-hash "$CI_MERGE_REQUEST_TARGET_BRANCH_SHA" \
      --start-point-clone-thresholds \
      --start-point-reset \
      --testbed debian:bullseye \
      --err \
      --adapter json \
      bencher mock

1. 更新 GitLab CI/CD 文件。 (例如：.gitlab-ci.yml)
2. 创建一个 GitLab CI/CD 任务。 (例如：benchmark_mr_branch)
3. 当管道是由merge_request_event触发时运行if。 请参阅 GitLab CI/CD rules 文档 和 GitLab CI/CD 预定义变量文档了解完整概览。 (例如：rules: if: ...)
4. 设置任务将运行的 image。 请参阅 GitLab CI/CD image 文档 了解完整概览。 (例如：image: debian:bullseye)
5. 使用便捷脚本安装 Bencher CLI。 (例如：before_script: ...)
6. 使用 bencher run CLI 子命令 运行您的合并请求分支的基准测试。 请参阅bencher run CLI 子命令了解完整概览。 (例如：bencher run)
7. 设置 --project 选项为项目slug。 请参阅--project 文档了解更多细节。 (例如：--project project-abc4567-wxyz123456789)
8. 设置 --token 选项为掩码的 BENCHER_API_TOKEN 环境变量。 请参阅--token 文档了解更多细节。 (例如：--token "$BENCHER_API_TOKEN")
9. 使用 GitLab CI/CD 预定义变量设置 --branch 选项为 MR 分支名称。 请参阅--branch 文档了解完整概览。 (例如：--branch "$CI_COMMIT_REF_NAME")
10. 为 MR 分支设置起始点：
    1. 使用 GitLab CI/CD 预定义变量设置 --start-point 选项为 MR 分支起始点。 请参阅--start-point 文档了解完整概览。 (例如：--start-point "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME")
    2. 使用 GitLab CI/CD 预定义变量设置 --start-point-hash 选项为 MR 分支起始点 git 哈希值。 请参阅--start-point-hash 文档了解完整概览。 (例如：--start-point-hash "$CI_MERGE_REQUEST_TARGET_BRANCH_SHA")
    3. 设置 --start-point-clone-thresholds 标志以从起始点克隆阈值。 请参阅--start-point-clone-thresholds 文档了解完整概览。 (例如：--start-point-clone-thresholds)
    4. 设置 --start-point-reset 标志以始终重置MR分支到起始点。 这将防止基准数据漂移。 请参阅--start-point-reset 文档了解完整概览。 (例如：--start-point-reset)
11. 设置 --testbed 选项为测试平台名称。 可能应该与在 image 中选择的机器匹配。 请参阅--tested 文档了解更多细节。 (例如：--testbed debian:bullseye)
12. 设置 --err 标志以便在生成警报时使命令失败。 请参阅--err 文档了解完整概览。 (例如：--err)
13. 设置 --adapter 选项为 Bencher Metric Format JSON (json)，生成可通过 bencher mock。 请参阅基准测试接口适配器了解完整概览。 (例如：--adapter json)
14. 指定基准测试命令参数。 请参阅基准测试命令了解完整概览。 (例如：bencher mock)

在 MR 关闭后清理 MR 分支， 您可以创建一个独立的作业，使用 GitLab API 查询 MR 状态。 如果状态是 closed，该作业将使用 bencher archive 命令存档 MR 分支。

archive_mr_branch:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: always
  image: debian:bullseye
  before_script:
    - curl --proto '=https' --tlsv1.2 -sSfL https://bencher.dev/download/install-cli.sh | sh
    - |
      MR_STATE=$(curl --header "PRIVATE-TOKEN: $CI_JOB_TOKEN" "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID" | jq -r .state)
      echo "Merge request state: $MR_STATE"
  script:
    - |
      if [ "$MR_STATE" = "closed" ]; then
        bencher archive \
        --project project-abc4567-wxyz123456789 \
        --token "$BENCHER_API_TOKEN" \
        --branch "$CI_COMMIT_REF_NAME"
      else
        echo 'Merge request is not `closed`. Skipping archival.'
      fi

1. 更新 GitLab CI/CD 文件。 （例如：.gitlab-ci.yml）
2. 创建一个 GitLab CI/CD 作业。 （例如：archive_mr_branch）
3. 在管道由 merge_request_event 触发时运行 if。 查看 GitLab CI/CD rules 文档 和 GitLab CI/CD 预定义变量文档 以获得完整概览。 （例如：rules: if: ...）
4. 设置作业将运行的 image。 查看 GitLab CI/CD image 文档 以获得完整概览。 （例如：image: debian:bullseye）
5. 使用便利脚本安装 Bencher CLI。 （例如：before_script: curl ...）
6. 使用 GitLab API 检查 MR 状态。 （例如：before_script: MR_STATE=$(...)）
7. 使用 bencher archive CLI 子命令存档 MR 分支 如果 MR 状态是 closed。 （例如：bencher archive）
8. 设置 --project 选项为项目代号。 查看 --project 文档 获取更多详情。 （例如：--project project-abc4567-wxyz123456789）
9. 将 --token 选项设置为屏蔽的 BENCHER_API_TOKEN 环境变量。 查看 --token 文档 获取更多详情。 （例如：--token "$BENCHER_API_TOKEN"）
10. 使用GitLab CI/CD 预定义变量将 --branch 选项设置为 MR 分支名称。 （例如：--branch "$CI_COMMIT_REF_NAME"）

🐰 恭喜！您已学会如何在 GitLab CI/CD 中使用 Bencher！🎉

继续前进：基准测试概览 ➡