cli-anything-unrealinsights

Que fait cli-anything-unrealinsights ?

Utilisez ce CLI lorsque vous avez besoin d'un accès orienté agent aux workflows de capture et d'exportation de traces Unreal Insights sur Windows.

Prérequis

• Windows
• Outils Unreal Engine installés avec UnrealInsights.exe
• Validé avec UE 5.5 ; les exportateurs de chronométrage en mode non-interactif incluent une gestion de compatibilité pour l'analyse des commandes de style UE 5.3 lorsque c'est possible
• Variables d'environnement explicites optionnelles :
  • UNREALINSIGHTS_EXE
  • UNREAL_TRACE_SERVER_EXE
  • UNREALINSIGHTS_TRACE

Commandes principales

Découverte du backend

cli-anything-unrealinsights --json backend info

Pour utiliser le UnrealInsights.exe correspondant à un moteur compilé depuis les sources :

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

Cette commande cherche d'abord Engine\Binaries\Win64\UnrealInsights.exe dans le répertoire racine du moteur spécifié, puis le compile avec Build.bat de ce moteur si nécessaire.

État de la session de trace

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

Découverte du Trace Store

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

Orchestration de capture

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

Vous pouvez également utiliser la forme explicite :

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'

Contrôle de session de capture continue

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

Ce flux est préféré lorsqu'un agent doit démarrer le profilage immédiatement et arrêter ou prendre un instantané plus tard dans un tour suivant.

Si une session de capture suivie est toujours en cours, capture start nécessite désormais --replace afin que le processus précédent soit arrêté avant qu'un nouveau ne soit lancé.

Backend de contrôle de trace en direct

$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 livraison de commandes en direct nécessite UNREALINSIGHTS_LIVE_EXEC ou --backend-command. Si aucun backend n'est configuré, les commandes en direct renvoient une erreur JSON et ne déclarent pas de succès. live stop-trace arrête la collecte de trace sans tuer le processus UE ; capture stop termine toujours l'arborescence de processus lancée par le harnais.

Copilote de l'interface graphique

cli-anything-unrealinsights --json gui status
cli-anything-unrealinsights --json gui open --trace D:\captures\session.utrace
cli-anything-unrealinsights --json gui open-latest

Les commandes GUI omettent -NoUI et -AutoQuit afin qu'Unreal Insights reste ouvert.

Exportateurs hors ligne

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

Préférez les filtres par joker avec la forme égale comme --timers=* et --counter=*. Le harnais transmet des valeurs simples à UnrealInsights sans guillemets internes afin que les jokers restent utilisables dans -ExecOnAnalysisCompleteCmd.

Fichiers de réponse par lot

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

Résumés d'analyse

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

Le résumé rapporte les temporisateurs principaux, les goulots d'étranglement ciblés (GameThread/RenderThread/RHIThread), les temporisateurs liés aux attentes/tâches, les pics de compteurs et les domaines non couverts pour une future analyse Mémoire/Réseau/Slate/Asset/Cooking.

analyze summary renvoie également export_status et summary.diagnostics.export_status_counts afin que les agents puissent distinguer les exportations réussies des combinaisons trace/filtre qui se sont terminées mais n'ont produit aucune ligne.

Guide de sortie JSON

• Préférez --json pour les workflows d'agent.
• Les commandes d'exportation renvoient :
  • trace_path
  • exec_command
  • output_files
  • output_status
  • status_message
  • log_path
  • exit_code
  • warnings
  • errors
  • succeeded
• La capture renvoie :
  • command
  • trace_path
  • trace_exists
  • trace_size
  • pid ou exit_code
• Le statut de capture continue renvoie :
  • pid
  • running
  • target_exe
  • project_path
  • trace_path
  • trace_size
  • started_at
• Les commandes Trace Store renvoient :
  • store_dir
  • trace_count
  • traces
  • latest
• Les commandes en direct renvoient :
  • pid
  • live_command
  • backend
  • exit_code
  • succeeded
• Le résumé d'analyse renvoie :
  • exports
  • export_status
  • summary.top_timers
  • summary.focus_threads
  • summary.wait_timers
  • summary.counter_peaks
  • summary.diagnostics
  • summary.uncovered_domains

Considérez output_status == "ok" comme une exportation matérialisée. Considérez output_status == "no_output" comme un résultat trace/filtre vide, pas un crash du backend. Utilisez exporter_error, process_failed et timed_out pour les décisions de réessai ou de débogage.

Remarques

• v1 est prioritairement Windows.
• v1 inclut la navigation dans le Trace Store, l'ouverture/statut de l'interface graphique, la livraison de commandes en direct enfichable et les résumés de chronométrage/compteurs.
• capture stop est un arrêt au mieux de l'arborescence de processus lancée par le harnais.
• capture snapshot est un instantané au mieux du système de fichiers de la trace active.
• Les tests de régression découvrent automatiquement l'exemple example_trace.decomp.utrace d'UE lorsqu'il est présent ; la trace binaire n'est pas vendue.