游戏引擎 / 系统课时

把 Profiling 接入流水线

把 Profiling 接入流水线

手工打开 Unreal Insights 适合深入定位,却无法保证每次提交都采到同样的数据。本节把性能采集拆成构建、运行固定场景、生成 Trace、提取指标、执行回归门槛和保存产物几个阶段,让 Profiling 成为 CI 中可重复、可追溯的一条链路。

学习目标

  • 能规划从构建到 Trace、指标和回归判定的自动化链路。
  • 能在无人值守环境中启动固定性能场景并把 .utrace 保存为流水线产物。
  • 能把原始证据、结构化指标和门槛结果绑定到同一个构建版本。

先把流水线拆成稳定阶段

性能流水线不应只是“运行一个 profiler 命令”。可靠流程通常包含:产出可测试构建、部署到固定执行机、运行可重复场景、采集 Trace、提取机器可读指标、执行门槛脚本、保存结果。任何阶段失败都应停止后续判定,避免拿缺失或半截数据做比较。

Unreal Profiling 持续集成链路

采集机要尽量固定 CPU、GPU、驱动、系统电源策略和后台负载。构建机可以弹性扩容,但真正用于性能比较的执行机不宜随机漂移,否则硬件差异会被误判成代码回归。

让测试场景可以无人值守结束

CI 最关键的前置条件不是 Trace 开关,而是“场景能自动开始并自动结束”。可以为项目准备专用性能地图、自动移动的 Camera Path 或 Functional/Automation 测试逻辑,并在固定预热后执行固定时长的采样。

不要让脚本依赖人工按键开始录制或关闭程序。性能构建应能在场景结束后自行退出,并用进程退出码表示运行是否成功。这样采集脚本只负责启动程序、等待完成和检查产物,不需要猜测场景状态。

在命令行写出 Trace 文件

Unreal 的 Trace 通道可以通过启动参数启用。下面的 PowerShell 脚本把一个已经能自动完成性能场景并退出的 Windows 构建作为输入,启用 cpu、gpu、frame 和 bookmark 通道,并把 Trace 写入指定目录。

powershell
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 工作区决定。

powershell
pwsh .\ci\capture-perf.ps1 -ExePath "C:\Build\MyGame.exe"

预期输出中的文件路径固定,Trace 文件大小和场景运行时间则会随构建变化。

text
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 由此从一次性的人工操作,变成每个版本都能重复执行和追溯的工程检查。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

把 Profiling 接入流水线

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通