cli-anything-unrealinsights

cli-anything-unrealinsights은(는) 무엇을 하나요?

Windows에서 언리얼 인사이트 트레이스 캡처 및 내보내기 워크플로우에 에이전트 친화적인 접근이 필요할 때 이 CLI를 사용하세요.

사전 요구 사항

• Windows
• UnrealInsights.exe가 포함된 언리얼 엔진 도구 설치
• 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 핫스팟, 대기/작업 관련 타이머, 카운터 피크 및 향후 메모리/네트워크/Slate/에셋/요리 분석을 위한 미처리 도메인을 보고합니다.

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에는 트레이스 스토어 찾아보기, GUI 열기/상태, 플러그형 라이브 명령 전달, 타이밍/카운터 요약이 포함됩니다.
• capture stop은 실행기에서 시작된 프로세스 트리를 최선의 방식으로 중지합니다.
• capture snapshot은 활성 트레이스의 파일 시스템 스냅샷을 최선의 방식으로 만듭니다.
• 회귀 테스트는 UE example_trace.decomp.utrace 샘플이 있을 때 자동으로 검색합니다. 바이너리 트레이스는 제공되지 않습니다.