CI 整合效能分析

CI 整合效能分析是指為自動建置送出的遙測資料加上 build_id，再於 Framedash 中查看各建置的效能。現階段已提供建置篩選、Regression 頁面、framedash builds、由 CI 執行的 framedash perf-diff 閘門、framedash run-profile-test 執行器、閾值設定檔與靜態閾值警報。Framedash 尚未提供代管的效能分析工作或代管的前次建置差異通知。

運作方式

CI 建置: 建立遊戲的建置
自動測試: 自動執行預先定義的情境
遙測收集: SDK 帶著 CI build_id 傳送效能資料
儀表板檢查: 使用 Regression 頁面或建置篩選比較建置
CI 閘門: 執行 framedash run-profile-test（或 framedash builds + framedash perf-diff）在建置間退化時讓建置失敗
選用警報: 以閾值設定檔和警報規則監控 FPS、影格時間或記憶體的靜態閾值

設定

1. 在 CI 環境中設定 SDK

初始化 SDK 時，從 CI 環境變數設定 build_id。

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 建置及其分支/提交/情境資訊。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 以最上層欄位的形式寫入；分支、提交和情境透過 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 顯示記憶體（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 及更新版本（opt-in、非無頭）、Unity SDK 0.1.4 及更新版本，或 Godot SDK 0.1.5 及更新版本。對於沒有 mem.vram 資料的建置，該指標會被視為無法比較。這是由 CI 執行並管理通過/失敗的指令閘門，不是代管的前次建置警報。

你也可以在儀表板中設定靜態閾值：

FPS 低於可接受下限
影格時間超過 33ms
記憶體使用量超過預算

活用範例

Pull Request 效能檢查: 將遙測連到 PR 建置，並在合併前檢查
每夜建置監控: 依 build ID 保留每日效能快照
發布前品質閘門: 使用 framedash perf-diff 或 CI 自有靜態閾值判定

下一步

CLI 參考: 在 CI 管線中活用 CLI
熱力圖: 效能的視覺化

針對 AI 代理: llms.txt