セルフサービスパフォーマンスリグレッションテスト

チームが独自にパフォーマンスリグレッションテストを実行するためのガイド

概要

このガイドは、チームが Performance Enablement のサポートを必要とせずに独自のパフォーマンスリグレッションテストを実行できるようにします。

対象者：何をテストして、なぜテストするかを理解しているチーム。新しいコンポーネントをテストする方法の定義が必要な場合は、Performance Enablement にエスカレーションしてください。

このガイドを使用する場面

負荷下でのパフォーマンスを検証する
パフォーマンスリグレッションの主要なアップグレードをテストする
インフラ変更前にパフォーマンスを検証する

前提条件

開始前に以下を確認してください：

スキルと経験

GitLab Environment Toolkit (GET) の経験：以前にリファレンスアーキテクチャをデプロイしたことがある（または GET クイックスタートガイドに従える）
GitLab Performance Tool (GPT) の経験：GPT でデータをロードしてテストを実行したことがある（または GPT クイックスタートガイドに従える）
変更の理解：どのコンポーネント / フィーチャーをテストするか、なぜテストするかを知っている

アクセスとアカウント

GitLab Sandbox へのアクセス
プレリリースイメージへのプルアクセスを持つ GitLab.com アカウント
サンドボックスアカウント内の GCP/AWS アカウント

準備できているか不確かな場合？ 上記の GET と GPT クイックスタートガイドをレビューしてください。行き詰まった場合は、Performance Enablement にエスカレーションしてください。

このガイドを作業で使用する方法

このハンドブックページは、パフォーマンスリグレッションテストを実行するための包括的な実装ガイダンスを提供し、進捗を追跡するための GitLab プロジェクトの Issue テンプレートと対になっています。Performance Regression Testing テンプレートを使用してワークアイテムを作成して開始してください。

これらのリソースを一緒に使用する方法

このハンドブックページを読む - 完全なプロセスと実装の詳細を理解するため
テンプレートを使用してワークアイテムを開く - 進捗と結果を追跡するため
各フェーズを進める際にこのハンドブックの特定のセクションを参照する
チームの可視性のためにワークアイテムに調査結果を文書化する

ハンドブックページは「なぜ」と「どのように」の詳細を提供し、ワークアイテムテンプレートは進捗を追跡するための「何を」チェックリストを提供します。

クイックデシジョンツリー

flowchart TD
    %% Nodes
    Prep["準備<br/>（テストと成功基準の定義、アーキテクチャの選択）"]
    Setup["セットアップ<br/>（GCP、GET 設定、デプロイ、シードデータ）"]
    baseline{ベースラインが<br>必要？}
    Baseline_test["ベースラインテスト<br/>（テスト実行、結果キャプチャ）"]
    Upgrade_test["アップグレードとテスト<br/>（アップグレード、テスト実行、結果キャプチャ）"]
    Analysis["分析<br/>（比較、文書化、クリーンアップ）"]
    Upgrade{アップグレード<br>テストが必要？}

    %% Map
    Prep --> Setup
    Setup --> baseline
    baseline -->|いいえ| Upgrade_test
    baseline -->|はい| Baseline_test
    Baseline_test --> Upgrade
    Upgrade -- はい -->Upgrade_test
    Upgrade -- いいえ --> Analysis
    Upgrade_test --> Analysis

    %% Links
    click Prep "#test-preparation"
    click Setup "#setup-testing"
    click Baseline_test "#baseline-testing"
    click Upgrade_test "#upgrade-testing"
    click Analysis "#analysis-and-results"

テスト準備

flowchart LR
    %% Nodes
    Testing["テストの<br/>定義"]
    Success["成功基準の<br/>特定"]
    Architecture["リファレンスアーキテクチャの<br/>選択"]
    Test_image["テストイメージの<br/>特定"]

    %% Map
    Testing --> Success
    Success --> Architecture
    Architecture --> Test_image


    %% Links
    click Testing "#define-testing"
    click Success "#identify-success-criteria"
    click Architecture "#choose-reference-architecture"
    click Test_image "#identify-test-image"

テストの定義

チームはすでに何をテストして、なぜテストするかを理解しているはずです。

テストするコンポーネント / フィーチャー
評価する変更（例：Rails 7.2 アップグレード、Ruby 3.3 アップグレード）
予想される影響領域（API レスポンス時間、スループット、メモリ使用量）

このステップには、実行するテストを決定し、実行に必要なテストツールを選択することも含まれます。この例では GPT がテストツールとして選択されていますが、他にも使用できるものがあります：

GPT がテストツールとして選択された場合、多くのテストと事前定義された負荷レベルを使用できます。

希望するユースケースをカバーする既存のテスト / 負荷レベルがない場合は、新しいものを書く必要があります。

スコープに不確かな場合：先に進む前に Performance Enablement にエスカレーションしてください。

成功基準の特定

パフォーマンステストを実行するとき、成功がどのようなものかを把握することで、成功と失敗、または無駄な努力の違いが生まれます。努力を導くために成功がどのようなものかを知っておく必要があります。そうしないと、必要な情報をキャプチャできず、テストを再実行しなければならないかもしれません。いくつかの例：

ベースラインからパフォーマンスが低下しなかった
ベースラインと比較してパフォーマンスが X% 改善した
負荷下での新しいフィーチャーのパフォーマンス特性を特定した
このコンポーネントのベースラインを確立した

成功基準の決定の一部は、比較するベースラインが何であるかを決定することです。使用できる既存のベースラインがあるか、新しいベースラインを実行するべきか。またはベースラインを確立することが目標か？

ベースラインテストは、後続の比較テストなしでも価値あるパフォーマンスメトリクスを生成します。現在のシステムパフォーマンスを文書化するチームは、それが目標を満たすならベースラインを実行した後に停止することができます。

重要な考慮事項

トンネルビジョンを避ける：非常に具体的な目標を持ってパフォーマンステストに入ること（Workhorse P95 メトリクスで 2 ms のレスポンスを期待する）は、そのスコープにない興味深い結果を見逃すトンネルビジョンにつながる可能性がある。
テスト結果は本番に 1:1 で変換されない：テスト環境でのパフォーマンス改善は本番に 1:1 で変換されない。テスト環境での 3 ms の改善は本番での改善につながるかもしれないが、異なるハードウェア、負荷パターン、データ特性により程度が異なる。

リファレンスアーキテクチャの選択

特定の理由がない限り、X Large リファレンスアーキテクチャを使用してください。

X Large アーキテクチャが提供するもの：

複雑さとリソース使用量の良いバランス
十分に文書化されてテストされている
公開されているパフォーマンスベンチマークに合致する
リアルなテストのための十分な HA コンポーネント

以下の場合のみ別のサイズを使用：

HA を必要としないコンポーネントをテストする → Medium を使用する
本番規模でテストする → 2X Large またはそれ以上を使用する
Geo や特定の機能をテストする → 適切なアーキテクチャを使用する（例：Geo セットアップ）

リファレンスアーキテクチャサイジングガイドを使用してアーキテクチャの決定に役立てることができます。サンプルの GET 設定を含む、いくつかのリポジトリがあります：

どれを使用するか不確かな場合：X Large リファレンスアーキテクチャをデフォルトとする。

テストイメージの特定

変更を担当するチームと調整してイメージ URL を取得してください。 彼らが最新バージョンを持っており、特別な考慮事項を提供できます。

一般的なイメージソース（参考として）：

MR / ブランチアーティファクト：MR / ブランチパイプライン上のジョブアーティファクト
ナイトリービルド：packages.gitlab.com/gitlab
Master パイプライン：最新の成功したビルド
リリース候補：次バージョンのプレリリースビルド
Docker Hub：hub.docker.com/u/gitlab
Dev ビルド：dev.gitlab.org/gitlab/omnibus-gitlab

注意： ⚠️ Web パイプラインアーティファクトページからイメージ URL を取得する場合は、URL を API エンドポイントを使用するように変換する必要があります。

Master パイプラインからのイメージ URL キャプチャまたはブランチパイプラインからのイメージ URL キャプチャを参照して URL をキャプチャし、変換してください：

https://<URL>/gitlab/omnibus-gitlab/-/jobs/<JOB_ID>/artifacts/file/pkg/ubuntu-noble/...

から

https://<URL>/api/v4/projects/gitlab%2Fomnibus-gitlab/jobs/<JOB_ID>/artifacts/pkg/ubuntu-noble/...

URL のテストは以下で行えます

curl -H "PRIVATE-TOKEN: $PRIVATE_PROD_TOKEN" \
  "https://dev.gitlab.org/api/v4/projects/gitlab%2Fomnibus-gitlab/jobs/<JOB_ID>/artifacts/pkg/ubuntu-noble/<PACKAGE_NAME>.deb" \
  -o /tmp/test.deb -L

file /tmp/test.deb  # Should show "Debian binary package"

詳細は GET 設定の準備セクションを参照してください

文書化すること：

イメージ URL
バージョン / コミット情報
イメージのソース（更新されたイメージを取得する必要がある場合に備えて）

テストのセットアップ

flowchart LR
    %% Nodes
    GET_prep["GET 設定の<br/>準備"]
    Test_infra["テストインフラの<br/>セットアップ"]

    %% Map
    GET_prep --> Test_infra

    %% Links
    click GET_prep "#prepare-get-configuration"
    click Test_infra "#setup-test-infrastructure"

GET 設定の準備

ほとんどの作業は GET クイックスタートガイドでカバーされています。

重要なセクションは gitlab_deb_download_url の設定です。

先に特定したテストイメージを GET が使用するように、ansible の vars.yml ファイルに以下を追加してください：

all:
  vars:
  # ... existing vars ...

    gitlab_repo_script_url: "https://packages.gitlab.com/install/repositories/gitlab/nightly-builds/script.deb.sh"
    gitlab_deb_download_url: "{{ lookup('env','GITLAB_UBUNTU_IMAGE') | default('https://gitlab.com/api/v4/projects/14588374/jobs/11423868576/artifacts/pkg/ubuntu-jammy/gitlab.deb', true)}}" # update to use latest image url
    gitlab_deb_download_url_headers: {
        "PRIVATE-TOKEN": "{{ lookup('env','PRIVATE_PROD_TOKEN')}}",
    } # use your .com token

  # ... rest of file ...

GPT テストの場合：必要なレート制限が無効になっていること、カスタムポストコンフィギュレーションタスクが使用されていることを確認してください。https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit-configs/quality/-/blob/main/custom_task_files/gitlab_tasks/post_configure.yml#L1-35 は自動的に適用されます（https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit-configs/quality/-/blob/main/configs/reference_architectures/10k/ansible/inventory/vars.yml#L24-40 と https://gitlab.com/gitlab-org/gitlab-environment-toolkit/-/blob/main/docs/environment_advanced.md#custom-tasks を参照）。

テストインフラのセットアップ

負荷テストはテスト環境のできるだけ近くから実行することをお勧めします（インターネットレイテンシを含めたテストを検討している場合は除く。これは通常、テストの範囲外です）。

GCP では、n2-standard-2 VM で十分です。大量のテストを実行する予定がある場合は、ブートディスクサイズを 100 GB に増やすと、実行途中でディスクスペースが不足するのを防ぐのに役立ちます。

VM に GPT をインストールする。
環境のための環境設定ファイルをセットアップする。

ベースラインテスト

flowchart LR
    %% Nodes
    deploy["ベース環境の<br/>デプロイ"]
    baseline_test["ベースライン<br/>テストの実行"]

    %% Map
    deploy --> baseline_test

    %% Links
    click deploy "#deploy-base-environment"
    click baseline_test "#run-baseline-test"

ベース環境のデプロイ

環境の立ち上げにリンクしています。ベースラインを実行するには、システムが今日どのように機能するかを反映したバージョンの環境を立ち上げます。そのため、gitlab_deb_download_url パラメータをコメントアウトすることになるでしょう。

ベースラインテストの実行

比較メトリクスを確立するために、ベースライン環境に対して GPT を実行してください。

手順：「パフォーマンステストの実行」を参照

ベースライン固有：

現在のイメージを使用する（テストイメージとして特定したカスタムイメージではない）
タイムスタンプ付きでベースライン結果を文書化する
baseline_metrics_YYYY-MM-DD.csv として結果を保存する

注意：ベースラインの生成 / 現在のシステムパフォーマンスの文書化が目標の場合、チームはテストを停止して直接調査結果の文書化に進むことができます。

アップグレードテスト

flowchart LR
    %% Nodes
    deploy["環境の<br/>アップグレード"]
    test["アップグレード後<br/>テストの実行"]

    %% Map
    deploy --> test

    %% Links
    click deploy "#upgrade-environment"
    click test "#run-post-upgrade-test"

環境のアップグレード

テスト対象の変更を実装するために必要な変更を加えて、環境の立ち上げ手順を再実行してください。ベースラインテストのために gitlab_deb_download_url パラメータをコメントアウトした場合は、コメントを解除してください。

アップグレード後テストの実行

アップグレードされた環境に対して同じテスト設定を実行してください。

手順：「パフォーマンステストの実行」を参照

アップグレード後固有：

アップグレードされたイメージを使用する
タイムスタンプ付きでアップグレード後の結果を文書化する
post-upgrade_metrics_YYYY-MM-DD.csv として結果を保存する

分析と結果

flowchart LR
    %% Nodes
    compare["結果の比較"]
    document["調査結果の文書化"]
    cleanup["クリーンアップ"]

    %% Map
    compare --> document
    document --> cleanup

    %% Links
    click compare "#compare-results"
    click document "#document-findings"
    click cleanup "#cleanup"

結果の比較

ベースライン対アップグレード後のメトリクスを比較する
公開された閾値と照合する
パフォーマンスリグレッションを特定する
結果の解釈を確認する

調査結果の文書化

結果のサマリーを作成する
懸念のあるメトリクスを記録する
エスカレーションが必要かどうかを判断する

クリーンアップ

テスト環境と VM を破棄する
- GET（GitLab Environment Toolkit）の場合
```
# Ansible による撤去
cd <ansible_folder_in_GET>
. ./get-python-env/bin/activate
ansible-playbook -i environments/<ENV_NAME>/inventory playbooks/uninstall.yml

# Terraform による撤去
cd <terraform_folder_in_GET>
terraform destroy
```
- 将来負荷テストを実行することが予想される場合は、テストロードジェネレーターを破棄する代わりにオフ状態のままにしておくこともできる。
GCP リソースがクリーンアップされたことを確認する
- GET 外で作成したリソース（外部 IP アドレスなど）に特に注意する

環境の立ち上げ

環境のデプロイ

GET で環境をプロビジョニングするのは以下のように簡単です：

cd <terraform_folder_in_GET>
terraform apply

Terraform が完了したら、Ansible の設定を実行してください：

cd <ansible_folder_in_GET>
. ./get-python-env/bin/activate
ansible-playbook -i environments/<ENV_NAME>/inventory playbooks/all.yml

注意：これらのタスクは両方とも実行に時間がかかります。待機の準備をしてください。

パフォーマンスデータのシード

環境をシードするには、テストインフラのセットアップでセットアップしたロードジェネレーターを使用してください。環境設定ファイルがデータをロードしている環境用にセットアップされていることを確認してください。詳細は GPT 環境準備ドキュメントで確認できます。水平データと垂直データの両方をシードすることをお勧めします。

GPT に組み込まれたテストジェネレーターは以下のように実行されます：

docker run -it \
  -e ACCESS_TOKEN=your-access-token \
  -v $(pwd)/config:/config \
  -v $(pwd)/results:/results \
  gitlab/gpt-data-generator --environment my-env.json -u

-u フラグは無人実行を有効にします。

別のリポジトリをロードしたい場合は、--large-project-tarball=/home/user/<CUSTOM PROJECT TARBALL>.tar.gz フラグで使用するためのプロジェクトの tarball を含めることができます。利用可能な代替 tarball。

注意：データのロードには 1〜2 時間かかることがあります。接続が切断された場合でもデータのロードが継続するように、screen セッションで実行することをお勧めします。

パフォーマンステストの実行

GPT でテストを実行するのは以下のように簡単です：

docker run -it \
  -e ACCESS_TOKEN=<TOKEN> \
  -v <HOST CONFIG FOLDER>:/config \
  -v <HOST TESTS FOLDER>:/tests \
  -v <HOST RESULTS FOLDER>:/results \
  gitlab/gitlab-performance-tool --environment <ENV FILE NAME>.json --options 60s_500rps.json --tests <TEST FILE>.js

テストを実行する前に、必要なメトリクスをキャプチャするためにシステムがセットアップされていることを確認してください（テストから直接結果として、またはオブザーバビリティから）。

テスト完了後、比較のためにメトリクスをキャプチャして保存してください：

テストのパス / 失敗統計
テストツールからのレスポンスタイミング
オブザーバビリティからのシステムメトリクス

成功基準に関連するメトリクスを必ずキャプチャしてください。

Master パイプラインからのイメージ URL キャプチャ

この例では、e2e-run-master でのテスト実行からキャプチャしています。

e2e-run-master Slack チャンネル

Pipeline リンクをクリックしてください。

パイプラインビュー

GitLab アップストリームを展開して build-images ジョブを見つけてください：

build-images ステージ

build-gdk-image ジョブで、ビルドされた URL が表示されています：

イメージ URL

URL は以下にあります： Built image 'registry.gitlab.com/gitlab-org/gitlab/gitlab-qa-gdk:2fe86491afa3db4d9b48c06302e295f038863c11'

ブランチパイプラインからのイメージ URL キャプチャ

この例では rails-next パイプラインからイメージをプルしています。

Rails Next パイプライン

ダウンストリームパイプラインを展開してください。

ダウンストリームパイプライン

trigger-omnibus ジョブを開いてください。これでイメージをビルドする別のパイプラインが開きます。

omnibus パイプライン

アーキテクチャに合わせて package ステージの適切なジョブを選択し（ここでは Ubuntu-24.04-branch を使用）、アーティファクトを表示してください。

アーティファクト

この場合、pkg > ubuntu-noble というフォルダを数回ナビゲートする必要がありました。

*.deb ファイルの URL をコピーして、GET の GITLAB_UBUNTU_IMAGE 環境変数として使用するために保存してください。

この場合の URL は：

https://gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/-/jobs/12607844542/artifacts/file/pkg/ubuntu-noble/gitlab-ee_18.7.0+rfbranch.2245624022.06bed6be-0_amd64.deb

注意： ⚠️ ジョブアーティファクトは 1〜2 日以内に有効期限が切れて削除されるため、テスト環境を再構築する必要がある場合はイメージ URL を再キャプチャする必要があるでしょう。

結果の解釈

ベースラインとアップグレード後のテストを実行した後、メトリクスが何を意味するかを理解する必要があります。

メトリクスはいくつかの方法で分析できます：

GPT は閾値に対する比較のサマリーを生成します
生の出力を確認する
- 出力をスプレッドシートに読み込んで比較する（例のように行われた）
- 比較するスクリプトを書く
- グラフを生成する（スクリプト / 他のツール）
- 手動で結果を比較する

このフレームワークを使用して結果を評価して次のステップを決定してください。

グリーン（順調）

メトリクスが公開された閾値内
ベースライン対比で有意なリグレッションなし（差異 < 5%）
パフォーマンスが安定または改善
アクション：結果を文書化してテストをクローズする

イエロー（注意が必要）

メトリクスが閾値をわずかに上回っている（5〜10% 超過）
ベースライン対比でわずかなリグレッション（5〜10% 遅い）
根本原因を調査する。最適化が必要かもしれない。
アクション：パフォーマンストレードオフがユースケースに対して許容可能かどうかを判断する。許容可能な場合は変更されたベースラインを文書化して進む。そうでない場合は最適化の機会を調査する。

レッド（再作業が必要）

メトリクスが閾値を著しく上回っている（> 10% 超過）
ベースライン対比で主要なリグレッション（> 10% 遅い）
負荷下で機能が壊れる
アクション：根本原因を調査して修正を実施する。改善を確認するために変更後にテストを再実行する。

混在した結果

結果が混在している場合（一部のメトリクスがグリーン、一部がイエローまたはレッド）、変更に最も関連性の高いメトリクスに焦点を当ててください。トレードオフを文書化して、許容できない問題を修正してください。

メトリクス比較の例

ベースラインとアップグレード後の結果を比較する場合：

メトリクス	ベースライン	アップグレード後	変化	ステータス
API レスポンス時間 (p95)	250ms	260ms	+4%	グリーン
スループット (RPS)	195	192	-1.5%	グリーン
エラーレート	0.1%	0.15%	+0.05%	グリーン
メモリ使用量	4.2GB	4.5GB	+7%	イエロー
CPU 使用率	65%	68%	+4.6%	グリーン

この例では、メモリ使用量がわずかに増加（イエロー）していますが、他のメトリクスは許容可能な範囲内（グリーン）です。これはメモリの増加に対する調査を保証しますが、必ずしもアップグレードをブロックするわけではありません。

実際の例

Rails 7.2 アップグレードテスト

Rails 7.2 アップグレードテスト（#579847）は完全なワークフローを示しています：

セットアップ：

Rails 7.2 omnibus パッケージで 10k 環境をデプロイ
MR アーティファクトからのカスタムイメージを使用
パッケージの互換性のために Jammy（Ubuntu 22.04）を設定
水平と垂直のパフォーマンスデータをシード

ベースラインテスト：

ベースライン環境に対して 60s_200rps.json 設定を実行
比較のために Grafana メトリクスをエクスポート
タイムスタンプ付きですべての結果を文書化

アップグレードとテスト：

環境に Rails 7.2 アップグレードを適用
新バージョンが実行されていることを確認
同じ 60s_200rps.json 設定を実行
テスト結果をキャプチャ
アップグレード後の Grafana メトリクスをエクスポート（グラフのスクリーンショット）

結果：

Google Sheet でテスト実行からのベースラインとアップグレード後のメトリクスを比較
Grafana グラフエクスポートを視覚的に比較
リファレンスアーキテクチャベンチマークと照合
パフォーマンスリグレッションを特定
Issue に調査結果を文書化

主な学び：

不安定な接続によるテストの中断を防ぐために screen コマンドを使用する
テスト前にレート制限が無効になっていることを確認する
正確な比較のためにタイムスタンプ付きで Grafana メトリクスをエクスポートする

詳細な結果と分析については、全 Issue を参照してください：#579847

Ruby 3.3 アップグレードテスト

Ruby 3.3 アップグレードテスト（#516194）はベースライン比較手法を示しています：