cli-anything-unrealinsights

cli-anything-unrealinsights

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

前提条件

• 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

トレースストアの検出

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
• トレースストアのコマンドは以下を返します:
  • 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 サンプルを 自動検出します。バイナリトレースは同梱されていません。