cli-anything-unrealinsights

O que cli-anything-unrealinsights faz?

Use esta CLI quando precisar de acesso amigável a agentes para fluxos de trabalho de captura de rastros e exportação do Unreal Insights no Windows.

Pré-requisitos

• Windows
• Ferramentas do Unreal Engine instaladas com UnrealInsights.exe
• Verificado com UE 5.5; exportadores de temporização headless incluem tratamento de compatibilidade para análise de comandos estilo UE 5.3, quando possível.
• Variáveis de ambiente opcionais:
  • UNREALINSIGHTS_EXE
  • UNREAL_TRACE_SERVER_EXE
  • UNREALINSIGHTS_TRACE

Comandos Principais

Descoberta de backend

cli-anything-unrealinsights --json backend info

Para usar o UnrealInsights.exe correspondente a um motor compilado a partir do código-fonte:

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

Isso primeiro procura por Engine\Binaries\Win64\UnrealInsights.exe na raiz do motor especificada e, em seguida, compila usando Build.bat desse motor, se necessário.

Estado da sessão de rastro

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

Descoberta do Trace Store

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

Orquestração 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

Você também pode usar a 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'

Controle de sessão de captura contínua

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 é o fluxo preferido quando um agente precisa iniciar o profiling agora e parar ou capturar um snapshot em uma etapa posterior.

Se uma sessão de captura rastreada ainda estiver em execução, capture start agora exige --replace para que o processo anterior seja interrompido antes de iniciar um novo.

Backend de controle de rastro ao 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

A entrega de comandos ao vivo requer UNREALINSIGHTS_LIVE_EXEC ou --backend-command. Se nenhum backend estiver configurado, os comandos ao vivo retornam um erro JSON e não reivindicam sucesso. live stop-trace para a coleta de rastros sem encerrar o processo UE; capture stop ainda encerra a árvore de processos lançada pelo harness.

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

Os comandos da GUI omitem -NoUI e -AutoQuit para que o Unreal Insights permaneça aberto.

Exportadores offline

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

Prefira filtros curinga no formato de igual, como --timers=* e --counter=*. O harness passa valores simples para o UnrealInsights sem aspas internas, para que os curingas permaneçam utilizáveis dentro de -ExecOnAnalysisCompleteCmd.

Arquivos de resposta em lote

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

Resumos de análise

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

O resumo informa os principais temporizadores, pontos críticos focados em GameThread/RenderThread/RHIThread, temporizadores relacionados a espera/tarefas, picos de contadores e domínios não cobertos para análise futura de Memória/Rede/Slate/Ativos/Compilação.

analyze summary também retorna export_status e summary.diagnostics.export_status_counts para que os agentes possam distinguir exportações bem-sucedidas de combinações de rastro/filtro que foram concluídas, mas não produziram linhas.

Diretrizes de Saída JSON

• Prefira --json para workflows de agentes.
• Comandos de exportação retornam:
  • trace_path
  • exec_command
  • output_files
  • output_status
  • status_message
  • log_path
  • exit_code
  • warnings
  • errors
  • succeeded
• Captura retorna:
  • command
  • trace_path
  • trace_exists
  • trace_size
  • pid ou exit_code
• Status de captura contínua retorna:
  • pid
  • running
  • target_exe
  • project_path
  • trace_path
  • trace_size
  • started_at
• Comandos do Trace Store retornam:
  • store_dir
  • trace_count
  • traces
  • latest
• Comandos ao vivo retornam:
  • pid
  • live_command
  • backend
  • exit_code
  • succeeded
• Resumo de análise retorna:
  • exports
  • export_status
  • summary.top_timers
  • summary.focus_threads
  • summary.wait_timers
  • summary.counter_peaks
  • summary.diagnostics
  • summary.uncovered_domains

Trate output_status == "ok" como uma exportação materializada. Trate output_status == "no_output" como um resultado de rastro/filtro vazio, não uma falha do backend. Use exporter_error, process_failed e timed_out para decisões de repetição ou depuração.

Notas

• v1 é prioridade para Windows.
• v1 inclui navegação no Trace Store, abertura/status da GUI, entrega de comandos ao vivo plugável e resumos de temporização/contadores.
• capture stop é uma tentativa de melhor esforço para encerrar a árvore de processos lançada pelo harness.
• capture snapshot é um snapshot de sistema de arquivos de melhor esforço do rastro ativo.
• Testes de regressão descobrem automaticamente a amostra example_trace.decomp.utrace do UE quando presente; o rastro binário não é distribuído.