UE4 Performance Profiling Automation With Unreal Insights
For those working on a mid to large video game with tons of assets on Unreal Engine, you might already know that performance optimization is always an issue. In here I’ll try to explain the workflow of my performance test automation in a simple way so we can always catch performance issues early on and debug it using Unreal Insights tool.
First, we need to create an automation test for our game, for reference on creating automation test in UE4 you can see here.
Ideally, a performance automation would need to cover every scenario that we want the player to see smoothly on a given device specification. Total War Warhammer have a very good example on how an automation benchmark should be done. Depending on your game, it might need different scenario.
After we have created our automation, we can run them from UE4 CLI. I’m assuming that the below code is how we setup our test:
IMPLEMENT_SIMPLE_AUTOMATION_TEST(FPerformanceTests_Level1, "PerformanceTest.Level1", EAutomationTestFlags::EditorContext | EAutomationTestFlags::ClientContext | EAutomationTestFlags::ProductFilter)
We can see that our test name is PerformanceTest.Level1
. We can run them with the command below
<path-to-UE4Editor.exe> <path-to-project> -ExecCmds="Automation RunTests PerformanceTest.Level1;Quit" -log=<log-filename>
Where:
- <path-to-UE4Editor.exe> pretty self explanatory, this is the path to your local UE4 executable
- <path-to-project> this is the path to your .uproject file
- <log-filename> optional, if you want to output the log somewhere else
By default it will be stored in<ProjectDir>/Saved/Logs
ps: You can add -game
args to run the test using uncooked assets
Now we can run our test easily, but to use Unreal Insight we need to add 1 more args to the command line. That is -trace=”<channel1>,<channel2>,…”
.
What is the channel? A channel is the parameter that we pass to the engine to determine what performance stats that we wanted to trace. For example,-trace=”cpu,gpu,frame”
will make cpu, gpu, and frame profiler events available to see.
Available channels are:
- Log
- Bookmark
- Frame
- CPU
- GPU
- LoadTime
- File
- Net
Unfortunately, UE4 docs doesn’t explain the details of the stat captured in every channel. But it should be self explanatory by the name (except bookmark, I don’t know what that is).
<path-to-UE4Editor.exe> <path-to-project> -ExecCmds="Automation RunTests PerformanceTest.Level1;Quit" -log=<log-filename> -trace="cpu,gpu,frame"
Listed above is the example of our complete command line.
-trace
args will make our test run generate a .utrace
file under <ProjectDir>/Saved/TraceSessions
. That is the file that we can use to view the performance stats in Unreal Insights.
Unreal Insights is a standalone tool. The tool ships with Unreal Engine and is located in the Engine/Binaries/Win64
directory. If you download the UE4 source code, you can compile it yourselves. More info on setup and usage can be found here.
Run the UnrealInsights.exe to open it. Then click the arrow besides the Open button to open the generated .utrace
file. If you forgot, it’s inside <ProjectDir>/Saved/TraceSessions
by default.
It will then visualize the stats for you
That’s it, you can see where an optimization might be needed, or identify bottleneck from here. Combined with the Automation Framework that UE4 already have, this is a powerful tools to identify performance problems early.
For more reference on how to use Unreal Insights, always refer to the docs here.