Profiling with Unreal Insights

NOTE: These instructions were written for UE 4.25, this tool is still in development

Unreal insights is the tool that is replacing the old stats profiler found in Unreal Frontend. They serve similar purposes but the UI is much easier to use in Insights as it shows an elapsed time view that shows how CPU/GPU time is sliced up and highlights thread contention issues. The official docs fully cover how to use the UI once you have a trace, but skip over the process for actually recording a trace. This page gives step-by-step instructions for recording and opening a trace:

Common Steps

1. First compile the UnrealInsights executable as described in docs, it would end up in Engine/Binaries/Win64 on windows

2. Package your game for the appropriate platform, you will need to use a method that supports setting a custom command line. This can be a shortcut for windows but is platform specific

3. For detailed CPU profiling add:

   -trace=log,counters,cpu,frame,bookmark,file,loadtime,gpu,rhicommands,rendercommands,object -statnamedevents to the packaged build command line. This will tell it to start recording those categories at startup. In 4.25 you need to specify the full list or use the TraceSourceFilters/TraceDataFilters plugins

4. That might be too heavy weight for some platforms, the minimal useful commandline is probably:

   -trace=counters,cpu,frame,bookmark,gpu

Live Tracing

This method connects tells the launched device to connect to an open copy of Unreal Insights

1. Launch Unreal Insights first

2. Add -tracehost=127.0.0.1 to your packaged build command line for mobile platforms. Use the host machine’s actual IP for PC/console builds

3. Launch your packaged build, it will try to connect to the open insights app and start saving trace data to the Trace Store Directory shown in the UI

4. Double click the Live session in the top window, this will open a live updating profiler view

5. If you go to Menu->Trace Data Filtering you may be able to enable/disable categories live

6. When you're done exit the game. The saved trace will remain in the directory and can be reopened later, and will stick around until deleted

Trace Recording

This method allows offline recording to disk but may lag the target device

1. Add -tracefile=PathToSaveTraceTo.utrace to command line. The specific path depends on the platform you are using so make sure it is one that is writable

2. Launch your packaged build, do interesting things, exit the game

3. Find the saved utrace file, copying it off the device if needed

4. Launch Unreal Insights

5. Click the down arrow next to Open and select the utrace file, this will open a profiler view

After using either method to get a trace, follow the instructions in the official documentation to navigate the profiler views.