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

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

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

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

CI のコミットやビルド識別子を build_id として SDK に渡すと、その実行のすべてのイベントが一つのビルドに紐付きます。

TelemetrySDK.Initialize(
    apiKey: System.Environment.GetEnvironmentVariable("FRAMEDASH_API_KEY"),
    buildId: System.Environment.GetEnvironmentVariable("FRAMEDASH_BUILD_ID"));

CI やデスクトップビルドでは、キー引数を空にすると Initialize が FRAMEDASH_API_KEY を環境変数から読み取ります。 解決順序の詳細は Unity SDK ガイドを参照してください。

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

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

TelemetrySDK.Instance.BeginAutomatedSessionFromEnvironment();
// ... プロファイリングシナリオを実行 ...
TelemetrySDK.Instance.EndAutomatedSession();

3. PlayMode テストからテレメトリーを送信する

Unity SDK はプレイヤーループ上で送信しますが、Edit モードではループが回りません。 -batchmode -executeMethod の単純な実行では、イベントはバッファされるだけで送信されません。 CI からテレメトリーを送信するには、PlayMode テスト（Unity Test Framework）でプレイヤーループを回し、テストをヘッドレスで実行します。

Unity.exe -batchmode -nographics -projectPath <path> -runTests -testPlatform PlayMode -testResults <path>\results.xml -logFile -

Test Framework に必要なアセンブリ定義や、配信を確認する HTTP 202 のログ行を含む完全なスモークテスト例は、Unity SDK ガイドにあります。

4. ゲートを実行する

framedash run-profile-test は FRAMEDASH_* セッション変数をエクスポートし、テストコマンドを起動し、テレメトリーの取り込みを待ってから、ベースラインに対して perf-diff ゲートを実行します。

framedash run-profile-test \
  --command "Unity.exe -batchmode -nographics -projectPath . -runTests -testPlatform PlayMode -logFile -" \
  --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 はゲームの取り込みキー用に残してください。

手動でステップを実行することもできます。

framedash builds --days 30

framedash perf-diff --baseline "$BASE_SHA" --candidate "$GITHUB_SHA" \
  --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.* のサンプルには Unity SDK 0.1.3 以降が必要です。 --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 の全フラグ
• Unity SDK ガイド：インストール、ヘッドレス実行、自動収集される指標