游戏引擎 / 系统课时
把 Profiling 接入流水线
把 Profiling 接入流水线
手工打开 Unreal Insights 适合深入定位,却无法保证每次提交都采到同样的数据。本节把性能采集拆成构建、运行固定场景、生成 Trace、提取指标、执行回归门槛和保存产物几个阶段,让 Profiling 成为 CI 中可重复、可追溯的一条链路。
学习目标
- 能规划从构建到 Trace、指标和回归判定的自动化链路。
- 能在无人值守环境中启动固定性能场景并把
.utrace保存为流水线产物。 - 能把原始证据、结构化指标和门槛结果绑定到同一个构建版本。
先把流水线拆成稳定阶段
性能流水线不应只是“运行一个 profiler 命令”。可靠流程通常包含:产出可测试构建、部署到固定执行机、运行可重复场景、采集 Trace、提取机器可读指标、执行门槛脚本、保存结果。任何阶段失败都应停止后续判定,避免拿缺失或半截数据做比较。

采集机要尽量固定 CPU、GPU、驱动、系统电源策略和后台负载。构建机可以弹性扩容,但真正用于性能比较的执行机不宜随机漂移,否则硬件差异会被误判成代码回归。
让测试场景可以无人值守结束
CI 最关键的前置条件不是 Trace 开关,而是“场景能自动开始并自动结束”。可以为项目准备专用性能地图、自动移动的 Camera Path 或 Functional/Automation 测试逻辑,并在固定预热后执行固定时长的采样。
不要让脚本依赖人工按键开始录制或关闭程序。性能构建应能在场景结束后自行退出,并用进程退出码表示运行是否成功。这样采集脚本只负责启动程序、等待完成和检查产物,不需要猜测场景状态。
在命令行写出 Trace 文件
Unreal 的 Trace 通道可以通过启动参数启用。下面的 PowerShell 脚本把一个已经能自动完成性能场景并退出的 Windows 构建作为输入,启用 cpu、gpu、frame 和 bookmark 通道,并把 Trace 写入指定目录。
param(
[Parameter(Mandatory = $true)]
[string]$ExePath,
[string]$ArtifactDir = "perf-artifacts"
)
$ErrorActionPreference = "Stop"
New-Item -ItemType Directory -Force -Path $ArtifactDir | Out-Null
$traceFile = Join-Path $ArtifactDir "run.utrace"
$process = Start-Process `
-FilePath $ExePath `
-ArgumentList "-trace=cpu,gpu,frame,bookmark", "-tracefile=$traceFile" `
-Wait `
-PassThru
if ($process.ExitCode -ne 0) {
throw "Performance scenario failed with exit code $($process.ExitCode)"
}
if (-not (Test-Path $traceFile)) {
throw "Trace file was not generated: $traceFile"
}
$size = (Get-Item $traceFile).Length
if ($size -le 0) {
throw "Trace file is empty: $traceFile"
}
Write-Output "TRACE_OK $traceFile"运行示例假设测试构建位于 C:\Build\MyGame.exe。实际路径由 CI 工作区决定。
pwsh .\ci\capture-perf.ps1 -ExePath "C:\Build\MyGame.exe"预期输出中的文件路径固定,Trace 文件大小和场景运行时间则会随构建变化。
TRACE_OK perf-artifacts\run.utrace.utrace 是定位证据,不应直接充当回归门槛输入。后续阶段应由项目自己的指标提取器把目标统计量写入 metrics.json,再交给门槛脚本处理。
把原始数据和判定结果一起保存
一次性能任务至少应保留三类产物:原始 .utrace、机器可读的 metrics.json、回归判定日志或报告。它们应带上同一个 Build ID、Commit SHA、目标平台、地图或场景名、分辨率、画质等级和执行机标识。
这种绑定很重要:门槛失败时,开发者先看结构化指标确认哪个维度超限,再打开同一次运行产生的 Trace 深挖 CPU、GPU 或任务调度,而不是重新手工复现一个可能已经不同的场景。
设计 CI 的失败语义
流水线中“采集失败”和“性能回归”要分开。程序崩溃、Trace 缺失、指标文件解析失败属于基础设施或测试失败;数据完整但超过门槛才属于性能回归。两者都可以阻断发布,但告警负责人和处理方式不同。
推荐让每个阶段只做一件事,并通过退出码传递状态:构建失败立即停止;场景运行失败不生成回归结论;指标提取失败保留 Trace 供排查;门槛脚本返回非零退出码时标记为性能回归。这样 CI 页面看到的失败点就能直接对应处理动作。
当这条链路稳定后,日常提交只需要查看门槛结果;真正发生退化时,再使用保存下来的 Trace 做深入分析。Profiling 由此从一次性的人工操作,变成每个版本都能重复执行和追溯的工程检查。