Meta Developers

Unreal Insights is a profiling and analysis tool that allows you to quickly find bottlenecks, performance spikes, threading patterns, and more. The goal of this guide is to help walk you through the setup process, which can otherwise be a bit tricky over a remote connection.

Requirements

Unreal Engine version 4.25+
Tracing enabled in built development app (on by default)
Unreal Insights executable built or downloaded (<CloneDir>\UnrealEngine\Engine\Binaries\Win64\UnrealInsights.exe and Solution ‘UE4’ > Programs > UnrealInsights in Solution Explorer)

Setup

Install the development app and verify the existence of /sdcard/UE4Game/<ProjectName>. You might need to launch the game for the first time for the binary to create its associated Unreal Engine project directory.
Instruct adb to pass through TCP connections made on the device over USB (Unreal Insights listens on TCP port 1980):
- adb reverse tcp:1980 tcp:1980
Edit your UE4CommandLine.txt file to do what you want:
- Locate the template file in <CloneDir>\UnrealEngine\Engine\Build\Android\UE4Game.
- Find UE4CommandLine.txt.template and copy/paste it, then remove the .template extension at the end.
- Add a line containing -tracehost=127.0.0.1 -cpuprofilertrace -statnamedevents
- Modify this file however you like. For the format, see below the following image for an example, along with an explanation of directories and arguments.
Open a command prompt to the folder containing UE4CommandLine.txt and copy the file to your project’s root directory on device.
- adb push UE4CommandLine.txt /sdcard/UE4Game/<ProjectDir>/
Open UnrealInsights.exe and check the box for Auto-start analysis for LIVE trace sessions if desired.
Go in your headset and run the map. You should see the trace being filled out in the Unreal Insights window.

../../../<ProjectName>/<UProjectName>.uproject /Game/Maps/<MapName> -trace=log,counters,cpu,frame,bookmark,file,loadtime,gpu,rhicommands,rendercommands,object -statnamedevents -tracehost=127.0.0.1 -tracefile=-tracefile=/sdcard/UE4Game/MostRecentTraceCapture.utrace

Notes on each directory/flag shown above:

<ProjectName> - The name of the Unreal Engine project. This will match the entry in /sdcard/UE4Game/<ProjectName>.
<UProjectName> - The UProjectName will match the output binary (dictated by the engine), so you can just use the APK name or find the .uproject file in your game’s directory.
<MapName> - This is optional, but it allows you to customize launch arguments on a per-map basis. If you know the map name, you can put it here.
Note: If you have a benchmarking scene that you are using, you can set up tracing for only that map so that the tracing overhead doesn’t affect other profiling on regular maps. This is nice because you can keep that launch argument file in the same location without having to remove or rename it between play types.
-trace - Allows you to define the channels to tap into for the trace. Here are some combinations that we use when profiling:
- Most Detail/Most Overhead - log,counters,cpu,frame,bookmark,file,loadtime,gpu,rhicommands,rendercommands,object
- Decent Detail/Minimal Overhead - counters,cpu,frame,bookmark,gpu
-statnamedevents - When combined with -trace=cpu option this will activate even more CPU timing events.
-tracehost - IP address of the host machine with the running Unreal Insights instance that you want to connect to (127.0.0.1).
-tracefile - Used to define a local path on the device that you want to dump the .trace file to as an alternative to live analysis. You can keep it in a static location and overwrite it each time to always keep a most recent trace.

Example

As an example, consider a project named QuestUnrealDemo based on the VR Template and set the default map to MotionControllerMap.The uproject is the same as the project, QuestUnrealDemo. The full package name is com.YourCompany.QuestUnrealDemo.

../../../QuestUnrealDemo/QuestUnrealDemo.uproject /Game/Maps/MotionControllerMap -trace=log,counters,cpu,frame,bookmark,file,loadtime,gpu,rhicommands,rendercommands,object -statnamedevents -tracehost=127.0.0.1 -tracefile=-tracefile=/sdcard/UE4Game/MostRecentTraceCapture.utrace

Push the updated UE4CommandLine.txt file to your project root directory on device.
- adb push UE4CommandLine.txt /sdcard/QuestUnrealDemo/
Launch Unreal Insights and check the Auto-start analysis for LIVE trace sessions checkbox if you want.
Launch your game. The live trace will start on launch within the Unreal Insights window.

Tips

The default PushCommandLine.bat file may push to the wrong location. You can edit it to push to where you want if you don’t want to type the adb push command every time you make a change. This is helpful if you want to frequently change your text file. You can edit yours to automatically push and reload the app for quick iteration. The script just includes:

%ANDROID_HOME%\platform-tools\adb.exe push UE4CommandLine.txt /mnt/sdcard/UE4Game/QuestUnrealDemo/UE4CommandLine.txt
%ANDROID_HOME%\platform-tools\adb.exe shell am force-stop com.YourCompany.QuestUnrealDemo
%ANDROID_HOME%\platform-tools\adb.exe shell am start -n com.YourCompany.QuestUnrealDemo/com.epicgames.ue4.GameActivity

Additional Useful Launch Flags for Profiling

-NoSound - Disable audio.
-NoTextureStreaming - Isolate hitches.
-NoVerifyGC - Avoids hitching in development builds.
-Benchmark - Run game at fixed-step in order to process each frame without skipping.
-ResX/ResY - Set the x and y resolution for the game to render at. Can force bottleneck to CPU this way.
-Dumpmovie - Dump rendered frames to files using the current resolution of the game. Useful to share a benchmark video for context.

Resources for Further Learning

Did you find this page helpful?