14 KiB
14 KiB
BC-R4 : capture de performance sans humain (CSV Profiler, PerfReportTool, Insights en ligne de commande, memreport, FPSChart, stat, build empaquetée)
Date 2026-10-15 ; auteur : sous-agent Sonnet OPT0-R ; 14 entrées ; répartition : 11 établi / 1 estimé / 2 non vérifié. R10 : +1 entrée(s) établi (R4-101…), voir BC-R10-SOURCES.md.
Recomptage : établi = R4-01 à R4-08, R4-10, R4-11, R4-12 (11) ; estimé = R4-13 (1) ; non vérifié = R4-09, R4-14 (2). Total 14.
Note de méthode : plusieurs pages Epic clés (aperçu du CSV Profiler en 5.x, usage de PerfReportTool, Trace en Shipping) n'ont pas pu être ouvertes (page vide ou HTTP 403). Les points qui ne reposent que sur des résumés de moteur de recherche sont renvoyés à « Lacunes et doutes » et ne figurent pas dans le tableau. Les pages de documentation Epic ouvertes portent le bandeau « Unreal Engine 5.8 » sans date de publication.
| id | affirmation (1-2 phrases, sans copie de texte) | source (URL, date, version UE) | niveau (établi / estimé / non vérifié) | application à LifePlay (système ou fichier) | action proposée | skill de destination |
|---|---|---|---|---|---|---|
| R4-01 | Le CSV Profiler se pilote entièrement au lancement : -csvCaptureFrames=N (nombre d'images), -csvCategories="A,B" (catégories), -csvMetadata="Clé=Valeur,..." (métadonnées dans le fichier), -csvCompression=0/1 (.csv ou .csv.gz), -csvRepeat=N, -csvCaptureOnEventFrameCount=N. | https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-command-line-arguments-reference (date inconnue, UE 5.8) | établi | Lanceur de banc d'essai (script PowerShell) : une seule ligne de commande suffit à produire un CSV sans humain. | Écrire un gabarit de ligne de commande avec -csvCaptureFrames et -csvMetadata (build, carte, scénario) pour identifier chaque capture. | lp-perf |
| R4-02 | -ExitAfterCsvProfiling fait quitter le processus à la fin de la capture CSV ; -unattended supprime fenêtres et dialogues ; -nullrhi lance sans rendu (inutilisable pour mesurer le GPU/rendu). | https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-command-line-arguments-reference (date inconnue, UE 5.8) | établi | Lancement non interactif : sortie propre du processus, donc banc enchaînable dans un script. Ne pas mettre -nullrhi pour des mesures de rendu. | Combiner -unattended -ExitAfterCsvProfiling ; documenter que -nullrhi ne vaut que pour la logique de jeu (CPU game thread). | lp-perf |
| R4-03 | -csvGpuStats active l'enregistrement des statistiques GPU dans le CSV (coût supplémentaire, désactivé par défaut) ; flags voisins listés sans description : -csvNamedEvents, -csvStatCounts, -csvNoProcessingThread, -csvTest. | https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-command-line-arguments-reference (date inconnue, UE 5.8) | établi | Rendu : mesures GPU par passe pour le banc ; à activer dans une seconde série de captures afin de ne pas fausser la série CPU. | Prévoir deux profils de capture (léger sans GPU stats, détaillé avec -csvGpuStats). | lp-perf |
| R4-04 | -ExecCmds="cmd1,cmd2" exécute des commandes console au lancement ; -EXEC=fichier exécute un fichier de commandes ; -FPS et -SECONDS fixent un pas de temps fixe et une durée maximale ; -BENCHMARK et -BENCHMARKSECONDS activent le mode benchmark (durée appliquée seulement dans ce mode). | https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-command-line-arguments-reference (date inconnue, UE 5.8) | établi | Déterminisme du banc : pas de temps fixe plus durée bornée donnent des captures comparables d'un run à l'autre ; commandes de scénario (ouverture de carte, stat, csvprofile) injectées sans éditeur. | Tester -BENCHMARK -FPS=n -BENCHMARKSECONDS=s sur une carte et vérifier que la capture a la longueur attendue (comportement exact de -FPS non précisé par la page). | lp-perf |
| R4-05 | -statnamedevents ajoute des événements nommés exploitables par Insights ; -statunit lance stat unit au démarrage. | https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-command-line-arguments-reference (date inconnue, UE 5.8) | établi | Lecture rapide frame/game/draw/GPU sans interface ; les événements nommés alourdissent la mesure, à réserver au diagnostic. | Ne pas laisser -statnamedevents dans le profil de verdict (surcoût) ; l'utiliser seulement en diagnostic. | lp-perf |
| R4-06 | Insights côté jeu : -trace=canal1,canal2 (ex. cpu,frame,bookmark,gpu,loadtime,log,memalloc,callstack,task,net), -tracehost=IP (envoi vers un serveur de traces, localhost par défaut), -tracefile ou -tracefile=nom (écriture dans un fichier .utrace), -tracetailmb=N (tampon de queue en Mo, 4 par défaut), -notraceserver, -TraceAutoStart=0/1. | https://dev.epicgames.com/documentation/unreal-engine/unreal-insights-reference-in-unreal-engine-5 (date inconnue, version non indiquée dans le texte lu ; URL « engine-5 ») | établi | Capture détaillée pour diagnostiquer une régression révélée par le CSV : fichier .utrace produit sans interface. | Profil « diagnostic » : -trace=cpu,frame,bookmark,gpu -tracefile=chemin absolu ; garder petit (canaux ciblés). | lp-perf |
| R4-07 | Sans chemin absolu, Trace.File écrit dans Projet/Saved/Profiling avec un nom horodaté ; commandes console Trace.Start [jeu de canaux], Trace.Stop, Trace.File [fichier] [jeu de canaux] ; jeux de canaux personnalisables dans [Trace.ChannelPresets]. UE_TRACE_ENABLED est actif par défaut (interrupteur général). | https://dev.epicgames.com/documentation/unreal-engine/unreal-insights-reference-in-unreal-engine-5 (date inconnue, UE 5.x) | établi | Config (Engine.ini [Trace.ChannelPresets]) pour nommer des profils de canaux réutilisables ; chemins de sortie du banc. | Définir un preset « bench » dans la config du projet et le référencer par -trace=bench ; vérifier sa prise en compte à l'essai. | lp-perf |
| R4-08 | Insights viewer en ligne de commande : UnrealInsights.exe -OpenTraceFile=fichier.utrace ouvre le fichier ; -OpenTraceId, -Store, -StoreHost, -StorePort pour un magasin de traces. L'API du module expose ScheduleCommand (commande exécutée une fois l'analyse terminée) et SetAutoQuit (fermeture à la fin de l'analyse) : l'analyse hors ligne scriptée est donc prévue. | https://dev.epicgames.com/documentation/unreal-engine/unreal-insights-reference-in-unreal-engine-5 et https://dev.epicgames.com/documentation/unreal-engine/API/Developer/TraceInsights/IUnrealInsightsModule (dates inconnues, UE 5.8 pour l'API) | établi | Analyse hors ligne des .utrace par script après la capture ; la page Epic ne documente pas les noms exacts des interrupteurs d'export. | Ne rien promettre sur l'export automatique avant un essai manuel de -AutoQuit / -ExecOnAnalysisCompleteCmd (voir R4-09). | lp-perf |
| R4-09 | Un encapsulage tiers (cli-anything) pilote UnrealInsights.exe avec -NoUI, -AutoQuit et -ExecOnAnalysisCompleteCmd pour exporter fils, statistiques de timers et valeurs de compteurs en CSV ; vérifié par l'auteur sur UE 5.5, avec jetons de statut (ok / no_output / process_failed / timed_out). Les valeurs avec jokers doivent être passées sans guillemets internes. | https://claudeskills.info/skills/hkuds/cli-anything/cli-anything-unrealinsights/ (date inconnue, UE 5.5) | non vérifié | Piste pour extraire des chiffres d'un .utrace sans humain ; source unique et tierce, jamais confirmée en 5.8. | Prototype d'essai : une trace de test, une exportation, comparaison avec l'interface ; ne l'adopter qu'après réussite en 5.8. | lp-perf |
| R4-10 | stat StartFile / stat StopFile écrivent un .uestats dans Projet/Saved/Profiling/UnrealStats, relisible dans le Profiler du Session Frontend ; le fichier peut grossir beaucoup, StartFile continue après la fermeture de PIE tant qu'on n'arrête pas. StartFPSChart / StopFPSChart et memreport ne figurent pas sur cette page. | https://dev.epicgames.com/documentation/unreal-engine/stat-commands-in-unreal-engine (date inconnue, UE 5.8) | établi | Outil de diagnostic ponctuel en éditeur/Development, peu adapté à un verdict automatique (format binaire, nécessite le frontend). | Préférer le CSV Profiler au verdict ; réserver StartFile à l'investigation manuelle ; toujours appairer avec StopFile. | lp-perf |
| R4-11 | La configuration Test est une Shipping avec une partie des commandes console, stats et outils de profilage réactivés ; Shipping retire commandes console, stats et profilage ; Development garde presque tout. La page ne dit pas, pour le CSV Profiler ni Insights, ce qui est compilé dans chaque configuration. | https://dev.epicgames.com/documentation/en-us/unreal-engine/build-configurations-reference-for-unreal-engine (date inconnue, UE 5.8) | établi | Choix de configuration du banc : mesurer en Test donne des chiffres proches de la version finale avec outils ; Development est plus lent donc pessimiste. | Construire le banc sur une build empaquetée Test (ou Development en repli), vérifier par un essai que csvprofile et -trace produisent un fichier, ne jamais viser Shipping. | lp-perf |
| R4-12 | Le plugin AutomatedPerfTesting (Engine/Plugins/Performance) fournit une classe de contrôleur de test avec EndTestFailure(code) : arrête le test et planifie la sortie du processus avec un code de sortie (1 par défaut, personnalisable, un code réservé par type d'échec systémique). | https://dev.epicgames.com/documentation/unreal-engine/API/Plugins/AutomatedPerfTesting/UAutomatedPerfTestControllerBase/EndTestFailure (date inconnue, UE 5.8) | établi | Verdict PASS/FAIL par code de sortie du processus : mécanisme natif pour faire échouer un run sur seuil. Seule la surface API a été lue, pas de guide d'usage. | Évaluer le plugin (activation, contrôleur, carte de test) ; sinon écrire un petit script qui lit le CSV puis renvoie un code non nul. | lp-autotest |
| R4-13 | PerfReportTool.exe (dossier Engine\Binaries\DotNET\CsvTools) : -csv fichier (un fichier) ou -csvdir dossier (lot, avec tableau de synthèse) ; -o dossier de sortie ; -reportType (Default60fps, Default30fps, Memory, définis dans ReportTypes.xml) ; -summaryTable (all, default, memory, condensed) ; -reportXML / -graphXML pour des définitions personnalisées ; -title ; -beginEvent / -endEvent ; -metadataFilter. Sortie : rapport HTML avec graphes. Liste complète dans PerfReportTool.cs. | https://qiita.com/EGJ-Ken_Kuwano/items/d43f305da17c8f63a10c (2019-12-22, UE 4.24) | estimé | Post-traitement du CSV en rapport HTML et en tableau comparable. Syntaxe de 4.24 : à revérifier avec l'exécutable de 5.8 (aide intégrée), des options ont pu changer. | Lancer PerfReportTool sans argument sur 5.8 pour relever l'aide réelle ; fixer un -reportType propre au projet (ReportTypes.xml copié) avec les seuils de budget. | lp-perf |
| R4-14 | Aucune source officielle ouverte ne donne de seuils standard PASS/FAIL ni de format de verdict : le verdict est à construire (lecture du CSV, comparaison à des budgets, code de sortie). Une annonce commerciale Fab (PerfGuard) revendique seuils par statistique et intégration Gauntlet/CI ; non vérifiée. | https://dev.epicgames.com/documentation/unreal-engine/API/Plugins/AutomatedPerfTesting/UAutomatedPerfTestControllerBase/EndTestFailure (absence de seuils, UE 5.8) ; vendeur : https://www.fab.com/listings/3af3bee7-22dd-4cf6-be53-364265b4a301 (apparu dans les résultats de recherche, non ouvert) | non vérifié | Conception du verdict du banc : budgets propres à LifePlay (par exemple p95 du temps d'image, mémoire maximale, nombre de hitches) à fixer après une base de référence. | Décider une méthode : médiane/percentile sur N captures, marge relative sur une référence enregistrée ; consigner le seuil dans un fichier versionné. | lp-validate |
| R4-101 | Les notes 5.8 présentent une vue Horde (expérimentale) des tendances du cadre de tests de performance automatisés (APT) et de csvprofiler : temps GPU/CPU, pic mémoire, saccades, pour détecter les régressions ; le stockage de base de données est à fournir. | https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-5-8-release-notes / date inconnue (lue 2026-10-15) / UE 5.8 | établi | Verdict de régression du banc : confirme APT + CSV comme chaîne officielle. | Utiliser APT/CSV pour le palier 1 ; Horde seulement si une base est disponible. | lp-perf |
Lacunes et doutes
- Page d'aperçu du CSV Profiler en UE 5.x : introuvable dans l'index dev.epicgames.com par la recherche ; la version 4.27 (docs.unrealengine.com) a répondu HTTP 403 à l'ouverture. Les points suivants proviennent donc de résumés de recherche non confirmés par une page ouverte, à tenir pour non vérifiés : commandes console csvprofile start / stop / frames=N, dossier de sortie Saved/Profiling/CSV, CSV Profiler indisponible en Shipping, statistiques GPU possibles en Test sans STATS.
- Options exactes de PerfReportTool en 5.8 : aucune page officielle lue ; la seule source ouverte date de 4.24 (R4-13). Il faut relever l'aide de l'exécutable 5.8.
- -ExecOnAnalysisCompleteCmd et -NoUI : seulement par un encapsulage tiers (R4-09) ; l'API Epic confirme l'existence de ScheduleCommand et d'auto-quit, pas la syntaxe en ligne de commande.
- memreport : seule la recherche en parle (rapport dans Saved/Profiling/MemReports, -full, sections [MemReportCommands] / [MemReportFullCommands] de la config, lancement via -ExecCmds) ; billet Epic de 2014, aucune page 5.x ouverte, donc aucune entrée. Un script doit tester que le rapport est produit.
- FPSChart (StartFPSChart / StopFPSChart) : mentions de forum UE4 seulement (HTML + CSV dans Saved/Profiling, arrêt ignoré si aucune capture) ; aucune page 5.x ouverte, donc aucune entrée. Un script doit vérifier lui-même l'existence du fichier de sortie.
- Insights dans une build Shipping/Test : la page de référence ne parle ni de Shipping ni de Test ; un guide tiers (AccelByte, non ouvert) indique qu'un .utrace n'est produit que si UE_TRACE_ENABLED est compilé. À éprouver sur la build empaquetée réelle.
- Comportement exact de -FPS (pas de temps fixe) et de -BENCHMARK en 5.8 : seule la brève description de la page de référence est lue.
- Seuils PASS/FAIL : aucune norme Epic trouvée (R4-14).
- Le thème est moyennement couvert en sources officielles 5.x ; le nombre de recherches a dépassé de quelques requêtes le cadre prévu pour tenter de combler l'aperçu du CSV Profiler.