Unreal Engine 5 のパフォーマンス回帰を CI で検出する

Unreal Engine 5 のパフォーマンス回帰をマージ前に止めるには、各ビルドのテレメトリーに build_id を付け、CI 上でプロファイリングシナリオを実行し、framedash perf-diff でパイプラインをゲートします。 候補ビルドが既知の良好なベースラインに対してしきい値を超えて悪化すると、コマンドは非ゼロで終了し、ジョブを失敗させます。 このガイドでは、Framedash の UE5 SDK（UE 5.3 以降向けの C++ プラグイン）でこの仕組みを構築します。

ビルドのタグ付けと回帰ゲートの考え方は、CI 統合プロファイリングを参照してください。

1. CI のビルド ID でタグ付けする

CI のコミットやビルド識別子を build_id として SDK に渡すと、その実行のすべてのイベントが一つのビルドに紐付きます。 C++ から初期化し、framedash run-profile-test（手順 3）がエクスポートする変数 FRAMEDASH_BUILD_ID を読み取って、テレメトリーの build_id をゲートが待つ値に一致させます。

if (auto* Subsystem = GetGameInstance()->GetSubsystem<UFramedashSubsystem>())
{
    FString ApiKey = FPlatformMisc::GetEnvironmentVariable(TEXT("FRAMEDASH_API_KEY"));
    FString BuildId = FPlatformMisc::GetEnvironmentVariable(TEXT("FRAMEDASH_BUILD_ID"));
    // EndpointUrl に空文字列を渡してデフォルト値を使用
    Subsystem->InitializeTelemetry(ApiKey, TEXT(""), BuildId);
}

別の変数（たとえば CI_COMMIT_SHA）でビルドをタグ付けする場合は、その同じ値を run-profile-test の --build-id にも渡して両者を一致させてください。 一致しないと、ゲートは取り込まれない build_id を待ち続けてタイムアウトします。 コードではなく設定で管理したい場合は、DefaultGame.ini の [/Script/Framedash.FramedashSettings] で BuildId を設定することもできます。 詳しい手順は UE5 SDK ガイドを参照してください。

2. 自動セッションにタグを付ける

テストのエントリーポイントで自動セッション API を一度呼び出します。 BeginAutomatedSessionFromEnvironment() は、framedash run-profile-test がエクスポートする FRAMEDASH_BUILD_ID / FRAMEDASH_GIT_BRANCH / FRAMEDASH_GIT_COMMIT / FRAMEDASH_TEST_SCENARIO を読み取ります。 これにより、イベントごとのタグ付けコードなしで、すべてのイベントにビルドと branch/commit/scenario が付与されます。

if (auto* Subsystem = GetGameInstance()->GetSubsystem<UFramedashSubsystem>())
{
    Subsystem->BeginAutomatedSessionFromEnvironment();
    // ... プロファイリングシナリオを実行 ...
    Subsystem->EndAutomatedSession();
}

3. 1 コマンドでゲートを実行する

framedash run-profile-test が最も簡単な方法です。 FRAMEDASH_* セッション変数をエクスポートし、プロファイリングビルドを起動し、テレメトリーの取り込みを待ってから、ベースラインに対して perf-diff ゲートを実行します。

framedash run-profile-test \
  --command "./Build/Game.exe -nullrhi -ExecCmds='Automation RunTest Perf'" \
  --scenario nightly --api-key-file ci-read.key \
  --baseline "$BASE_SHA" --threshold 5 --fail-on-regression

ゲートは analytics:read キーでテレメトリーを読み取り、起動されるゲームは別の events:write 取り込みキーでテレメトリーを送信します。 ゲートキーは --api-key-file で渡し、FRAMEDASH_API_KEY はゲームの取り込みキー用に残してください。

上のコマンドには、置き換えが必要なプレースホルダーが 3 つあります。

• ./Build/Game.exe: パッケージ化またはヘッドレスのゲームバイナリ。UE5 ビルドでは通常、素の .exe ではなくヘッドレス実行のセクションにある UnrealEditor-Cmd.exe <Project>.uproject <MapPath> -game -nullrhi ... の起動コマンドです。この -game 実行は自分では終了しないため、同セクションのタイムアウトラッパー（Windows は PowerShell の遅延後 kill、Linux / macOS は timeout / gtimeout）で打ち切り、成功判定はログの HTTP 2xx 行で行ってください。自分のビルドの実際の起動コマンドに置き換えてください。
• ci-read.key: ゲートがテレメトリーを読み取るために使う analytics:read API キーを格納したファイル。CI シークレットから作成します（例: printf '%s' "$FRAMEDASH_READ_KEY" > ci-read.key）。
• $BASE_SHA: 比較対象となる既知の正常なベースラインのコミットまたはビルド ID（例: 分岐時点の main の SHA）。手順 4 の $GITHUB_SHA はテスト対象の候補ビルドです。

CI で UE5 ビルドをヘッドレス実行するには、まずエディターターゲットをビルドし、null RHI でゲームを起動します。 正確な UnrealEditor-Cmd.exe の起動方法と、配信を確認するログ行は UE5 SDK ガイドにあります。

4. 手動でステップを実行する

各ステップを分けたい場合は、比較可能なビルド ID を確認し、候補をベースラインと比較します。 framedash run-profile-test は自身が起動したコマンドの中でしか FRAMEDASH_BUILD_ID を設定しないため、自分で実行を回す場合は好きなビルド ID で自分で FRAMEDASH_BUILD_ID をエクスポートし（手順 1 の初期化コードがこれを読みます）、同じ値を --candidate にも使ってください。

export FRAMEDASH_BUILD_ID="$GITHUB_SHA"
# ... launch your profiling run so the SDK tags telemetry with this build id ...

framedash builds --days 30

framedash perf-diff --baseline "$BASE_SHA" --candidate "$FRAMEDASH_BUILD_ID" \
  --threshold 5 --fail-on-regression

perf-diff はフレームタイム、メモリ、GPU 時間、マップロード時間（load_time_ms）、ディスク I/O（io.read_bytes / io.read_time_ms / io.read_ops）を、値が小さいほど良い（lower-is-better）指標として比較します。 マップロードと io.* のサンプルには UE5 SDK 0.1.6 以降が必要です。 --metric で対象指標を一つに絞ったり、--map や --platform で対象マップやプラットフォームを絞ったりできます。

REST での代替手段

CLI がない言語からゲートする場合も、同じ比較を REST で利用できます。 GET /v1/projects/{id}/builds がビルド ID を一覧し、GET /v1/projects/{id}/builds/compare が 2 つのビルドを比較します。 後者は baseline と candidate を必須とし、days / mapId / platform / fresh=1 を受け付けます。 詳細は API 概要を参照してください。

次のステップ

• CI 統合プロファイリング：概念と全体のセットアップ
• CLI リファレンス：perf-diff と run-profile-test の全フラグ
• UE5 SDK ガイド：インストール、ヘッドレス実行、自動収集される指標