cli-anything-unrealinsights

cli-anything-unrealinsights 是做什么的？

当您需要以代理友好的方式访问 Unreal Insights 的跟踪捕获和导出工作流时，请在 Windows 上使用此 CLI。

先决条件

• Windows
• 已安装 Unreal Engine 工具，包含 UnrealInsights.exe
• 已验证适用于 UE 5.5；无头时序导出器在可能的情况下包含对 UE 5.3 样式命令解析的兼容性处理
• 可选显式环境变量：
  • UNREALINSIGHTS_EXE
  • UNREAL_TRACE_SERVER_EXE
  • UNREALINSIGHTS_TRACE

核心命令

后端发现

cli-anything-unrealinsights --json backend info

使用源码构建的引擎对应的 UnrealInsights.exe：

cli-anything-unrealinsights --json backend ensure-insights `
  --engine-root 'D:\code\D5\d5render-ue5_3'

此命令首先在指定的引擎根目录下查找 Engine\Binaries\Win64\UnrealInsights.exe，如有必要，则使用该引擎的 Build.bat 进行构建。

跟踪会话状态

cli-anything-unrealinsights trace set D:\captures\session.utrace
cli-anything-unrealinsights --json trace info

Trace Store 发现

cli-anything-unrealinsights --json store info
cli-anything-unrealinsights --json store list --live-only
cli-anything-unrealinsights --json store latest --set-current

捕获编排

cli-anything-unrealinsights --json capture run `
  --project 'D:\Projects\MyGame\MyGame.uproject' `
  --engine-root 'D:\Program Files\Epic Games\UE_5.5' `
  --output-trace D:\captures\boot.utrace `
  --channels "default,bookmark" `
  --exec-cmd "Trace.Bookmark BootStart" `
  --wait --timeout 300

您也可以继续使用显式形式：

cli-anything-unrealinsights --json capture run `
  'D:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealEditor.exe' `
  --target-arg 'D:\Projects\MyGame\MyGame.uproject'

连续捕获会话控制

cli-anything-unrealinsights --json capture start `
  --project 'D:\Projects\MyGame\MyGame.uproject' `
  --engine-root 'D:\Program Files\Epic Games\UE_5.5' `
  --output-trace D:\captures\live_session.utrace

cli-anything-unrealinsights --json capture status
cli-anything-unrealinsights --json capture snapshot D:\captures\live_snapshot.utrace
cli-anything-unrealinsights --json capture stop

这是代理需要立即开始性能分析并在后续轮次中停止或快照时的首选流程。

如果跟踪的捕获会话仍在运行，capture start 现在需要 --replace 以在启动新进程前停止前一个进程。

实时跟踪控制后端

$env:UNREALINSIGHTS_LIVE_EXEC='ushell-wrapper --pid {pid} --cmd "{cmd}"'
cli-anything-unrealinsights --json live processes
cli-anything-unrealinsights --json live trace-status --pid 1234
cli-anything-unrealinsights --json live bookmark --pid 1234 "BeforeExport"
cli-anything-unrealinsights --json live stop-trace --pid 1234

实时命令传递需要 UNREALINSIGHTS_LIVE_EXEC 或 --backend-command。如果未配置后端，实时命令将返回 JSON 错误，不会声称成功。live stop-trace 停止跟踪收集而不终止 UE 进程；capture stop 仍然终止由 harness 启动的进程树。

GUI 副驾驶

cli-anything-unrealinsights --json gui status
cli-anything-unrealinsights --json gui open --trace D:\captures\session.utrace
cli-anything-unrealinsights --json gui open-latest

GUI 命令省略 -NoUI 和 -AutoQuit，使 Unreal Insights 保持打开状态。

离线导出器

cli-anything-unrealinsights --json -t D:\captures\session.utrace export threads D:\out\threads.csv
cli-anything-unrealinsights --json -t D:\captures\session.utrace export timer-stats D:\out\stats.csv --region=EXPORT_CAPTURE
cli-anything-unrealinsights --json -t D:\captures\session.utrace export counter-values D:\out\counter_values.csv --counter=*

优先使用等号形式的通配符过滤器，例如 --timers=* 和 --counter=*。harness 将简单值传递给 UnrealInsights 而不加内部引号，因此通配符在 -ExecOnAnalysisCompleteCmd 内部仍然可用。

批量响应文件

cli-anything-unrealinsights --json -t D:\captures\session.utrace batch run-rsp D:\out\exports.rsp

分析摘要

cli-anything-unrealinsights --json -t D:\captures\session.utrace analyze summary --out D:\out\summary
cli-anything-unrealinsights --json analyze summary --skip-export --out D:\out\summary

摘要报告顶级计时器、重点的 GameThread/RenderThread/RHIThread 热点、等待/任务相关计时器、计数器峰值以及未覆盖的域（供将来的 Memory/Network/Slate/Asset/Cooking 分析使用）。

analyze summary 还返回 export_status 和 summary.diagnostics.export_status_counts，以便代理区分成功导出与已完成但未生成行的跟踪/过滤器组合。

JSON 输出指南

• 对于代理工作流，优先使用 --json。
• 导出命令返回：
  • trace_path
  • exec_command
  • output_files
  • output_status
  • status_message
  • log_path
  • exit_code
  • warnings
  • errors
  • succeeded
• 捕获命令返回：
  • command
  • trace_path
  • trace_exists
  • trace_size
  • pid 或 exit_code
• 连续捕获状态返回：
  • pid
  • running
  • target_exe
  • project_path
  • trace_path
  • trace_size
  • started_at
• Trace Store 命令返回：
  • store_dir
  • trace_count
  • traces
  • latest
• 实时命令返回：
  • pid
  • live_command
  • backend
  • exit_code
  • succeeded
• 分析摘要返回：
  • exports
  • export_status
  • summary.top_timers
  • summary.focus_threads
  • summary.wait_timers
  • summary.counter_peaks
  • summary.diagnostics
  • summary.uncovered_domains

将 output_status == "ok" 视为具体化的导出。将 output_status == "no_output" 视为空跟踪/过滤器结果，而不是后端崩溃。使用 exporter_error、process_failed 和 timed_out 进行重试或调试决策。

备注

• v1 以 Windows 为首要平台。
• v1 包括 Trace Store 浏览、GUI 打开/状态、可插拔的实时命令传递以及时序/计数器摘要。
• capture stop 是对由 harness 启动的进程树进行尽力而为的停止。
• capture snapshot 是对活动跟踪文件的尽力而为的文件系统快照。
• 回归测试在 example_trace.decomp.utrace 示例存在时会自动发现它；二进制跟踪文件不包含在发行版中。