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.

BENCHMARK TESTS & RESULTS! : Total War: WARHAMMER 2 Performance

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.