CI 統合プロファイリング

CI 統合プロファイリングでは、自動ビルドから送信するテレメトリーに build_id を付け、Framedash 上でビルドごとのパフォーマンスを確認します。現時点で利用できるのは、ビルドフィルター、Regression ページ、framedash builds、CI 側で実行する framedash perf-diff ゲート、framedash run-profile-test ランナー、しきい値プロファイル、静的しきい値アラートです。Framedash がホストするプロファイリングジョブや前回ビルドとの差分通知はまだ未実装です。

仕組み

1. CI ビルド: ゲームのビルドを作成
2. 自動テスト: 事前定義されたシナリオを自動実行
3. テレメトリー収集: SDK が CI の build_id 付きでパフォーマンスデータを送信
4. ダッシュボード確認: Regression ページやビルドフィルターでビルドを比較
5. CI ゲート: framedash run-profile-test（または framedash builds + framedash perf-diff）でビルド間の回帰時にビルドを失敗させる
6. 任意のアラート: しきい値プロファイルとアラートルールで FPS、フレームタイム、メモリの静的上限/下限を監視

セットアップ

1. CI 環境での SDK 設定

SDK の初期化時に build_id を CI 環境変数から設定します。

Unity / Godot

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

UE5

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);
}

2. 自動セッションのタグ付け

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

Unity / Godot

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

UE5

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

build_id は最上位フィールドとして、branch/commit/scenario は ci.branch / ci.commit / ci.scenario 属性として付与されます。

3. テストシナリオの定義

各マップ/エリアを巡回するテストシナリオを作成し、一貫したデータを収集します。

4. プロファイリングゲートの実行

最も簡単な方法は framedash run-profile-test です: FRAMEDASH_* セッション変数をエクスポートし、プロファイリングビルドを起動し、テレメトリーの取り込みを待ってから、ビルド間の回帰時にジョブを失敗させます。

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

手動でステップを実行することもできます。比較可能なビルド ID を確認し、候補ビルドがしきい値を超えて悪化した場合にパイプラインを失敗させます:

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）、GPU VRAM（mem.vram）を lower-is-better 指標として比較します。マップロードと io.* のサンプルには Unity 0.1.3 / UE5 0.1.6 / Godot 0.1.4 以降の SDK が必要で、mem.vram には UE5 SDK 0.1.7 以降（オプトイン、非ヘッドレス）、Unity SDK 0.1.4 以降、または Godot SDK 0.1.5 以降が必要です。ベースラインにデータが無いビルドの mem.vram は比較不能（not comparable）として扱われます。ホスト型の前回ビルド差分アラートではなく、CI がコマンドを実行して合否を管理します。

ノート

ゲートは analytics:read キーでテレメトリーを読み取り、起動されるゲームは別の events:write 取り込みキーでテレメトリーを送信します。名前の衝突を避けるため、ゲートキーは FRAMEDASH_API_KEY 環境変数ではなく --api-key-file で渡し、FRAMEDASH_API_KEY はゲームの取り込みキー用に残してください。

ダッシュボードでは静的なしきい値も設定できます:

• FPS が許容下限を下回る
• フレームタイムが 33ms を超過
• メモリ使用量が予算を超過

活用例

• プルリクエストのパフォーマンスチェック: PR ビルドにテレメトリーを紐付け、マージ前に確認
• ナイトリービルドの監視: build ID ごとの日次パフォーマンススナップショットを残す
• リリース前の品質ゲート: framedash perf-diff または CI 側の静的しきい値で判定

次のステップ

• CLI リファレンス: CI パイプラインでの CLI 活用
• ヒートマップ: パフォーマンスの可視化