cli-anything-unrealinsights

¿Qué hace cli-anything-unrealinsights?

Usa esta CLI cuando necesites acceso amigable para agentes a los flujos de trabajo de captura y exportación de trazas de Unreal Insights en Windows.

Prerrequisitos

• Windows
• Herramientas de Unreal Engine instaladas con UnrealInsights.exe
• Verificado con UE 5.5; los exportadores de temporización sin interfaz incluyen manejo de compatibilidad para el análisis de comandos estilo UE 5.3 cuando sea posible
• Variables de entorno opcionales explícitas:
  • UNREALINSIGHTS_EXE
  • UNREAL_TRACE_SERVER_EXE
  • UNREALINSIGHTS_TRACE

Comandos principales

Descubrimiento del backend

cli-anything-unrealinsights --json backend info

Para usar el UnrealInsights.exe correspondiente a un motor compilado desde el código fuente:

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

Esto primero busca Engine\Binaries\Win64\UnrealInsights.exe bajo la raíz del motor especificado, luego lo compila con el Build.bat de ese motor si es necesario.

Estado de la sesión de traza

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

Descubrimiento del Trace Store

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

Orquestación de captura

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

También puedes seguir usando la forma explícita:

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'

Control de sesión de captura continua

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

Este es el flujo preferido cuando un agente necesita comenzar a perfilar ahora y detener o tomar instantáneas más tarde en un turno posterior.

Si una sesión de captura rastreada aún está en ejecución, capture start ahora requiere --replace para que el proceso anterior se detenga antes de lanzar uno nuevo.

Backend de control de traza en vivo

$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

La entrega de comandos en vivo requiere UNREALINSIGHTS_LIVE_EXEC o --backend-command. Si no hay backend configurado, los comandos en vivo devuelven un error JSON y no reclaman éxito. live stop-trace detiene la recolección de trazas sin matar el proceso de UE; capture stop aún termina el árbol de procesos lanzado por el harness.

Copiloto de 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

Los comandos de GUI omiten -NoUI y -AutoQuit para que Unreal Insights permanezca abierto.

Exportadores sin conexión

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

Prefiere filtros comodín con formato de igual como --timers=* y --counter=*. El harness pasa valores simples a UnrealInsights sin comillas internas, por lo que los comodines siguen siendo utilizables dentro de -ExecOnAnalysisCompleteCmd.

Archivos de respuesta por lotes

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

Resúmenes de análisis

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

El resumen informa los temporizadores principales, puntos calientes enfocados en GameThread/RenderThread/RHIThread, temporizadores de espera/tarea, picos de contadores y dominios no cubiertos para futuros análisis de Memoria/Red/Slate/Activos/Cocina.

analyze summary también devuelve export_status y summary.diagnostics.export_status_counts para que los agentes puedan distinguir exportaciones exitosas de combinaciones de traza/filtro que se completaron pero no produjeron filas.

Guía de salida JSON

• Prefiere --json para flujos de trabajo de agentes.
• Los comandos de exportación devuelven:
  • trace_path
  • exec_command
  • output_files
  • output_status
  • status_message
  • log_path
  • exit_code
  • warnings
  • errors
  • succeeded
• Capture devuelve:
  • command
  • trace_path
  • trace_exists
  • trace_size
  • pid o exit_code
• El estado de captura continua devuelve:
  • pid
  • running
  • target_exe
  • project_path
  • trace_path
  • trace_size
  • started_at
• Los comandos de Trace Store devuelven:
  • store_dir
  • trace_count
  • traces
  • latest
• Los comandos en vivo devuelven:
  • pid
  • live_command
  • backend
  • exit_code
  • succeeded
• El resumen de análisis devuelve:
  • exports
  • export_status
  • summary.top_timers
  • summary.focus_threads
  • summary.wait_timers
  • summary.counter_peaks
  • summary.diagnostics
  • summary.uncovered_domains

Trata output_status == "ok" como una exportación materializada. Trata output_status == "no_output" como un resultado de traza/filtro vacío, no un fallo del backend. Usa exporter_error, process_failed y timed_out para decisiones de reintento o depuración.

Notas

• v1 es primero en Windows.
• v1 incluye navegación del Trace Store, apertura/estado de GUI, entrega de comandos en vivo conectable y resúmenes de temporización/contadores.
• capture stop es una detención de mejor esfuerzo del árbol de procesos lanzado por el harness.
• capture snapshot es una instantánea de mejor esfuerzo del sistema de archivos de la traza activa.
• Las pruebas de regresión descubren automáticamente la muestra example_trace.decomp.utrace de UE cuando está presente; la traza binaria no está incluida.