cli-anything-unrealinsights

cli-anything-unrealinsights は何をしますか？

このCLIは、Windows上でUnreal Insightsのトレースキャプチャおよびエクスポーターワークフローにエージェントがアクセスする必要がある場合に使用します。

前提条件

• Windows
• UnrealInsights.exe を含むUnreal Engineツールがインストールされていること
• 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 の注目ホットスポット、待機/タスク関連タイマー、カウンターのピーク、および将来のメモリ/ネットワーク/スレート/アセット/コック分析のための未カバードメインを報告します。

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 サンプルが存在する場合に自動的に検出します。バイナリトレースはベンダリングされていません。