cli-anything-unrealinsights

cli-anything-unrealinsights 是做什麼的？

使用此 CLI 可在 Windows 上以代理程式友善的方式存取 Unreal Insights 的追蹤捕獲和匯出工作流程。

先決條件

• 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 仍會終止由啟動器啟動的程序樹。

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=*。啟動器會將簡單的值傳遞給 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 是對啟動器啟動之程序樹的盡力停止。
• capture snapshot 是對作用中追蹤的盡力檔案系統快照。
• 回歸測試會自動發現 UE 的 example_trace.decomp.utrace 範例（若存在）；此二進位追蹤檔案未隨附於此技能中。