Trace est un framework de journalisation structuré permettant de tracer les événements d'instrumentation d'un processus en cours d'exécution. TraceLog et TraceAnalysis sont les principaux modules qui le constituent. Le serveur Unreal Trace Server s'exécute en arrière-plan comme une instance de serveur unique et peut être partagé entre plusieurs projets ou branches. Il s'agit d'un programme optimisé sans interface utilisateur, et qui affecte peu les performances.
Trace Server est automatiquement lancé par un processus de serveur distinct (UnrealTraceServer.exe) disponible sous le dossier du répertoire Engine/Binaries/Win64.
Trace Server comporte deux composants :
Trace Recorder écoute les connexions de Trace entrantes sur le port 1981 et enregistre le flux de trace en direct.
Trace Store stocke les traces enregistrées sous forme de fichiers dans un dossier. Ce composant vérifie si des modifications sont apportées à ce dossier et affiche la liste des traces disponibles sur l'IU d'Unreal Insights.
Voici un exemple du chemin vers un dossier de trace :
C:/Users/<user>/AppData/Local/UnrealEngine/Common/UnrealTrace/Store/001/Unreal Trace Server
Les compilations de l'Unreal Editor lancent automatiquement UnrealTraceServer.exe lorsque vous vous connectez à partir du navigateur de session Unreal Trace. Le serveur Unreal Trace Server s'exécute en arrière-plan comme une instance de serveur unique et peut être partagé entre plusieurs projets et branches.
Pour arrêter Unreal Trace Server, vous pouvez accéder au Gestionnaire des tâches de votre système, puis à l'onglet Processus.
Unreal Trace Server s'exécute en arrière-plan comme une instance unique qui n'a pas besoin d'être arrêtée pour lancer une nouvelle version. Il peut recevoir et enregistrer des données provenant de plusieurs sources à la fois.
Actuellement, Unreal Trace Server n'est pris en charge que pour un seul utilisateur par machine. Si plusieurs utilisateurs sont connectés en même temps, les traces seront stockées dans le répertoire de trace du premier utilisateur et les autres utilisateurs ne pourront pas y accéder.
Widget Trace Insights
Le widget Trace Insights permet de contrôler et de gérer vos données Trace à l'aide d'une interface d'édition. Pour accéder au widget Trace Insights depuis l'éditeur, cliquez sur le bouton Trace dans la barre d'outils inférieure.
Les sections suivantes décrivent les paramètres des différentes catégories du menu Trace.
Données de traces
La catégorie Données de traces contient des paramètres relatifs aux canaux de données, aux signets Trace, aux captures d'écran Trace, etc.
Canaux
Trace est capable d'enregistrer de grands quantités de données. Vous pouvez choisir le type de données à enregistrer à l'aide des canaux de trace.
Les canaux contrôlent le débit des données lors du traçage. Chaque type d'événement est associé à un ou plus canaux. Si les canaux nécessaires ne sont pas activés, l'événement ne sera pas émis sur le flux de trace.
Les préréglages de canaux regroupent les canaux pour fournir des points de départ basés sur des scénarios.
| Channel | Description |
|---|---|
Animation | Animation Insights Plugin. |
AssetLoadTime | Contains named CPU timers for |
AssetMetadata | Asset Names and Class Names as metadata for memory allocations. Requires Metadata channel. Used by Memalloc channel. |
Audio | Audio Insights Plugin. |
AudioMixer | AudioMixer Insights Plugin. |
Bookmark | Low-frequency markers to signify important transitions. Bookmarks provide a quick overview of features such as level loading or engine boot phases. |
Callstack | Callstack descriptions. Allows allocations to be associated with callstacks. |
ContextSwitch | Trace context switch events. On Windows, game or editor runtime should be run as administrator. |
Cook | Displays named CPU timers specific to cooking. This requires the CPU channel to be enabled. Cook will add the both the |
Counters | Generic counters. Traces float and integer values over time. Counters Trace API. It enables the CSV Profiler Trace. |
Cpu | Named CPU timers. Additional timers can be added by enabling the Stat Named Events channel from the Insights Widget or using the |
File | File I/O trace channel that contains Open, ReOpen, Read, Write, Close events. |
Frame | Game and Rendering frames. |
Gpu | Named GPU timers. Based on GpuProfiler data. |
LoadTime | Asset Loading Insights trace channel. Only works for runtime loading from the pak/iostore. |
Log | Logs Messages. |
MemAlloc | Memory allocations. Uses Module and Callstack. |
MemTag | Memory tag statistics. Traces snapshots of memory usage per tag at regular rate. Relies on LLM subsystem for tracing. Implies "-llm". Available after |
Messaging | UDP Messaging plugin. |
Metadata | Support for generic metadata scopes. |
Module | Module loading information. |
Net | Networking trace channel. |
Niagara | Niagara Plugin. |
Object | GameplayInsights/RewindDebugger plugin. |
Physics | |
RDG | RDG Insights Plugin. |
RHICommands | CPU or GPU named timers for RHI commands. |
RenderCommands | CPU or GPU named timers for commands executed on the rendering thread. |
SaveTime | Named CPU timers specific to package saving. |
Screenshot | Captures screenshots triggered with |
Slate | Slate Insights Plugin. |
StackSampling | Trace stack sampling events based on Event Tracing for Windows (ETW). |
Stats | Stats counters. Based on the Stats system. |
Task | Task Graph trace channel. |
VisualLogger | Visual Logger starts recording to file. |
Les canaux suivants sont activés par défaut :
Signet
CPU
Image
GPU
Journal
Région
Capture d'écran
Les canaux MemAlloc, MemTag et Module sont grisés, car ils doivent être exécutés depuis l'invite de commande. Voir Depuis l'invite de commande
Vous pouvez définir vos propres préréglages à l'aide de fichiers de configuration ajoutés à la catégorie [Trace.ChannelPresets]. Consultez la documentation du Guide du développeur Trace pour en savoir plus.
Trace Screenshot
Trace Screenshot prend une photo du hublot de votre projet sur cette image et l'envoie à trace. Par défaut, Trace Screenshot est activé dans le panneau des canaux.
Vous pouvez prendre une capture d'écran de trace de deux façons :
Dans la barre d'outils inférieure, cliquez sur Trace > Trace Screenshot.
Dans la console, entrez la commande
trace.screenshot.
Lorsque vous utilisez Trace Screenshot, la chronologie Timing Insights affiche une ligne verticale contenant un nom généré en fonction de l'horodatage actuel, indiquant la date et l'heure de votre capture d'écran.
Trace Bookmark
Trace Bookmark émet un événement Trace_BookMarker() avec le nom de la chaîne spécifiée. Lorsqu'ils sont utilisés depuis l'éditeur, les événements de capture d'écran et de signet génèrent un nom basé sur l'horodatage actuel utilisant le format de date et heure.
Vous pouvez définir un signet Trace de deux manières :
Dans la barre d'outils inférieure, cliquez sur Trace > Signet Trace.
Dans la console, entrez la commande
Trace.bookmark.
Les signets et les captures d'écran sont visibles dans l'onglet Timing Insights. Vous les trouverez dans la piste des marqueurs ancrée dans la barre d'outils supérieure, sous la piste de la règle. Les signets sont disponibles dans la vue Journal.
Événements nommés de stat
Les événements nommés de stat fournissent des mesures de profilage supplémentaires. Vous pouvez les activer ou les désactiver en cochant la case Événements nommés de stat.
Destination de trace
La catégorie Destination de trace vous permet de choisir l'emplacement de stockage de vos données de trace.
| Option | Description |
|---|---|
Base de données des traces | Écrit les données de trace dans un fichier du répertoire de la base de données des traces gérée. |
Fichier | Écrit les données de trace directement dans le fichier spécifié. |
Traçage
La catégorie Traçage contient des paramètres pour démarrer et arrêter l'enregistrement, ainsi que pour enregistrer les captures d'écran de trace.
Démarrer et arrêter l'enregistrement
| Option | Description |
|---|---|
Démarrer la trace | Démarre une trace vers la destination de trace sélectionnée. Vous pouvez lancer une trace depuis le widget Trace Insights en cliquant sur le bouton Démarrer la trace. |
Arrêter la trace | Lorsqu'une trace est lancée, l'icône de l'IU Démarrer la trace s'affiche en rouge. Vous pouvez arrêter la trace en cliquant sur le bouton Arrêter la trace. |
Enregistrer une capture d'écran de trace
Il existe deux façons d'enregistrer une capture d'écran de trace :
Dans la barre d'outils inférieure, cliquez sur le bouton Enregistrer la capture d'écran de trace.
Dans la barre d'outils inférieure, cliquez sur Trace > Enregistrer une capture d'écran de trace.
Options
La catégorie Options contrôle l'automatisation, telle que l'ouverture automatique d'Unreal Insights ou de dossiers de destination.
| Option | Description |
|---|---|
Ouvrir une session en direct sur démarrage de la trace | Lorsque le traçage est lancé, la session en direct s'ouvre automatiquement dans l'Unreal Insights. Cette option ne s'applique que lors du traçage dans la base de données des traces. |
Ouvrir Insights une fois le traçage terminé | Lorsque le traçage est arrêté ou qu'une capture d'écran est enregistrée, la session enregistrée s'ouvre automatiquement dans l'Unreal Insights. |
Afficher dans l'explorateur après le traçage | Lorsque le traçage est arrêté ou qu'une capture d'écran est enregistrée, le dossier contenant la session enregistrée s'ouvre automatiquement. |
Emplacements
La catégorie Emplacements contrôle l'endroit où les traces (enregistrées dans le fichier et Trace Server) sont stockées.
| Option | Description |
|---|---|
Ouvrir le répertoire de la bases de données des traces | L'emplacement de stockage des traces enregistrées sur Trace Server. |
Ouvrir le répertoire des profils | Ouvre le répertoire des profils du projet en cours. Il s'agit de l'emplacement de stockage des traces vers le fichier. |
Insights
La catégorie Insights contient des paramètres qui ouvrent l'Unreal Insights, des sessions en direct et des fichiers enregistrés.
| Option | Description |
|---|---|
Unreal Insights(Navigateur de session) | Lance le navigateur de session Unreal Insights. |
Ouvrir une session en direct | Ouvre la session en direct actuelle. Cela n'est possible qu'en cas de traçage vers la base de données. |
Traces récentes | Ouvre les dernières traces enregistrées dans la base de données des traces ou dans un fichier. |
Statut de la trace
Vous pouvez vérifier les informations relatives à vos canaux de trace : Connexion, Mémoire utilisée, Cache d'événements importants, Données envoyées, Activés et Disponibles à l'aide de la commande de console Trace.Status.
Exécuter Insights à partir de l'invite de commande
Pour exécuter Unreal Insights à partir de l'invite de commande, procédez comme suit :
Accédez au dossier
Engine\Binaries\Win64et double-cliquez surUnrealInsights.exe.Lancez l'invite de commande depuis votre système d'exploitation et exécutez votre projet. Dans l'exemple suivant, remplacez le chemin d'installation et le nom du projet par les vôtres :
C++cd C:\[MyEngineInstallLocation]\ Samples\Games\Binaries\Win64\[YourProject].exe
Tail Tracing
Tail Tracing suit les événements survenus au cours des dernières secondes (en fonction de la taille du tampon). Par conséquent, toutes les machines peuvent afficher les événements précédents.
La taille par défaut du tampon est de 4 Mo. Vous pouvez toutefois la modifier ou la désactiver, à l'aide de la commande de console -tracetailmb=X.
Régler X sur une valeur de 0 Mo désactivera le tampon, tandis que des valeurs différentes modifieront sa taille.
Connexion tardive
Les événements importants sont mis en cache côté client Unreal Engine, puis envoyés aux machines qui se connectent tardivement. De cette manière, vous ne manquez aucun événement ponctuel (événement important) avant d'établir une connexion.
Insights peut demander aux instances Unreal Engine qui s'exécutent à distance de se connecter aux Trace Servers à distance à partir de leur instance d'IU locale sans requérir la machine locale.
Pour lancer la connexion tardive, vous pouvez accéder à Unreal Insights > Connexion, ou saisir l'une des commandes ou arguments suivants dans la console de l'éditeur :
"trace.send [ip]" / "trace.start [nom_fichier]"-trace.start [fichier] [channelSet] -tracehost=[ip]-tracefile = [chemin d'accès]
Unreal Insights dispose d'un système de mise en cache basé sur des fichiers qui permet à l'application d'ajouter des informations supplémentaires à une trace. Vous pouvez alors récupérer plus rapidement des résultats calculés précédemment ou stocker des données qui sans cela seraient perdues, comme des symboles. Le cache est stocké dans un fichier .ucache près du fichier de trace.
Guide d'utilisation de Trace
Vous pouvez utiliser différents flux de travail pour exécuter des traces dans l'Unreal Insights. Consultez le Guide d'utilisation de Trace pour obtenir de la documentation.
Guide du développeur Trace
L'Unreal Insights vous permet de développer vos propres traces. Consultez la documentation du Guide du développeur Trace pour en savoir plus.