cli-anything-unrealinsights

Was macht cli-anything-unrealinsights?

Verwenden Sie diese CLI, wenn Sie agentenfreundlichen Zugriff auf die Trace-Erfassung und Export-Workflows von Unreal Insights unter Windows benötigen.

Voraussetzungen

• Windows
• Unreal Engine-Tools mit installiertem UnrealInsights.exe
• Getestet mit UE 5.5; Headless-Timing-Exporter enthalten Kompatibilitätsbehandlung für UE 5.3-artige Befehlsanalyse, wo möglich
• Optionale explizite Umgebungsvariablen:
  • UNREALINSIGHTS_EXE
  • UNREAL_TRACE_SERVER_EXE
  • UNREALINSIGHTS_TRACE

Kernbefehle

Backend-Erkennung

cli-anything-unrealinsights --json backend info

Um das passende UnrealInsights.exe einer quellbasierten Engine zu verwenden:

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

Dies sucht zuerst nach Engine\Binaries\Win64\UnrealInsights.exe unter dem angegebenen Engine-Root und erstellt es dann mit dem Build.bat dieser Engine, falls erforderlich.

Trace-Sitzungsstatus

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

Trace Store-Erkennung

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

Erfassungsorchestrierung

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

Sie können auch die explizite Form verwenden:

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'

Kontinuierliche Erfassungssitzungssteuerung

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

Dies ist der bevorzugte Ablauf, wenn ein Agent jetzt mit dem Profiling beginnen und später in einem Folgeschritt stoppen oder einen Snapshot erstellen muss.

Wenn eine verfolgte Erfassungssitzung noch läuft, erfordert capture start jetzt --replace, damit der vorherige Prozess gestoppt wird, bevor ein neuer gestartet wird.

Live-Trace-Steuerungs-Backend

$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

Die Live-Befehlsübergabe erfordert UNREALINSIGHTS_LIVE_EXEC oder --backend-command. Wenn kein Backend konfiguriert ist, geben Live-Befehle einen JSON-Fehler zurück und behaupten keinen Erfolg. live stop-trace stoppt die Trace-Erfassung, ohne den UE-Prozess zu beenden; capture stop beendet weiterhin die gestartete Prozesshierarchie.

GUI-Co-Pilot

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-Befehle lassen -NoUI und -AutoQuit weg, sodass Unreal Insights geöffnet bleibt.

Offline-Exporter

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=*

Bevorzugen Sie Gleichheitsform-Wildcard-Filter wie --timers=* und --counter=*. Die Harness übergibt einfache Werte ohne innere Anführungszeichen an UnrealInsights, sodass Wildcards innerhalb von -ExecOnAnalysisCompleteCmd verwendbar bleiben.

Batch-Antwortdateien

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

Zusammenfassungen analysieren

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

Die Zusammenfassung meldet die Top-Timer, fokussierte GameThread/RenderThread/RHIThread-Hotspots, Warte-/Task-bezogene Timer, Zählerspitzen und unentdeckte Domänen für zukünftige Memory/Network/Slate/Asset/Cooking-Analysen.

analyze summary gibt auch export_status und summary.diagnostics.export_status_counts zurück, sodass Agenten erfolgreiche Exporte von Trace/Filter-Kombinationen unterscheiden können, die abgeschlossen wurden, aber keine Zeilen erzeugt haben.

JSON-Ausgabe-Richtlinien

• Bevorzugen Sie --json für Agenten-Workflows.
• Export-Befehle geben zurück:
  • trace_path
  • exec_command
  • output_files
  • output_status
  • status_message
  • log_path
  • exit_code
  • warnings
  • errors
  • succeeded
• Erfassung gibt zurück:
  • command
  • trace_path
  • trace_exists
  • trace_size
  • pid oder exit_code
• Status der kontinuierlichen Erfassung gibt zurück:
  • pid
  • running
  • target_exe
  • project_path
  • trace_path
  • trace_size
  • started_at
• Trace Store-Befehle geben zurück:
  • store_dir
  • trace_count
  • traces
  • latest
• Live-Befehle geben zurück:
  • pid
  • live_command
  • backend
  • exit_code
  • succeeded
• Zusammenfassung analysieren gibt zurück:
  • exports
  • export_status
  • summary.top_timers
  • summary.focus_threads
  • summary.wait_timers
  • summary.counter_peaks
  • summary.diagnostics
  • summary.uncovered_domains

Behandeln Sie output_status == "ok" als materialisierten Export. Behandeln Sie output_status == "no_output" als leeres Trace/Filter-Ergebnis, nicht als Backend-Absturz. Verwenden Sie exporter_error, process_failed und timed_out für Wiederholungs- oder Debugging-Entscheidungen.

Hinweise

• v1 ist Windows-zuerst.
• v1 enthält Trace Store-Durchsuchen, GUI-Öffnen/Status, steckbares Live-Befehls-Backend und Zeit-/Zähler-Zusammenfassungen.
• capture stop ist ein Best-Effort-Stopp der gestarteten Prozesshierarchie.
• capture snapshot ist ein Best-Effort-Dateisystem-Snapshot des aktiven Traces.
• Regressionstests erkennen automatisch die UE-Beispieldatei example_trace.decomp.utrace, wenn vorhanden; der binäre Trace wird nicht mitgeliefert.