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