Profiling on Device with Unreal Insights

Article written by Ryan B.

Unreal Insights helps developers identify bottlenecks, which is useful when optimizing for performance. At a high level, Unreal Insights is a stand-alone profiling system that integrates with Unreal Engine to collect, analyze, and visualize data emitted by the engine. In addition to providing robust coverage of the Engine’s existing systems, Unreal Insights makes it easy to add your profiling data. Finally, the system features the capability to record data remotely, minimizing the application’s impact on your project’s execution.

There are two parts to Unreal Insight: the trace code embedded in the Unreal Engine runtime, and the viewer application. Both are necessary to capture a trace in order to profile your application.

The Unreal Insights viewer is a standalone application that runs on the platforms supported by Unreal Editor (Windows, Mac, Linux), and it’s easy to connect the viewer application to the UE runtime, as the viewer application will automatically detect and display instances of the UE runtime running on the same computer, and it’s easy to add additional trace options via the command line when launching the UE runtime.

When profiling the UE runtime on a different device, there are additional challenges related to the network and the inability for some devices to accept command line arguments.

There are always potential challenges inherent in getting two applications on different devices to communicate over a network interface unrelated to the application or engine. Ensuring the devices are on the same network and subnet and the required ports are open are outside the scope of this article, but equally necessary. This may require some networking knowledge. If the device is wireless, the computer running the viewer application may also need to be on the wireless network in order to communicate.

Command Line Arguments

The Unreal Insights Reference lists the available command-line arguments to control the tracing behavior:

Available trace channels include:
Log, Bookmark, Frame, CPU, GPU, LoadTime, File, Net

You need to pass those arguments on the command line somehow, but some devices don’t support command line arguments. To get around this, UE has a text file (for UE4 it’s called UE4Commandline.txt) that you can add the command line arguments to directly. UE4 will load this early and treat it the same way it would any command line arguments. If the project has the default setting of combining all files into a single .pak file, this file is inside the .pak file. This file may in turn be inside a platform specific application bundle such as .apk for Android or .self for PS4, etc. In the case of an application that uses a .pak file, you may have to extract it with UnrealPak.exe (command line tool in the Binaries folder), change it, and re-compress it into the pak with the same tool. Alternatively , you can change the project’s packaging setting to not use pak files in the Project Settings > Packaging Settings section, though loose files may not be supported on all platforms, and even if it is, disabling .pak file and using loose files will probably result in slower loading times, as there is generally non-trivial overhead associated with all the different file handles that will result. If the platform has its own application bundle, you will have to investigate the tools for that platform to extract and re-package the application files into that bundle type.

To make this more simple, the Project Launcher has a field in the Launch settings called “Additional Command Line Parameters.” Here you can just add the trace options above, and re-package. Re-packaging may take a long time with a large application since it runs through all the cooking and packaging steps, so the above manual method of editing the command line text file may be preferable to save that time.

Supported Platforms
Generally, Unreal Insights is supported on all platforms. But currently it is enabled and disabled per-platform in Engine\Source\Runtime\TraceLog\Public\Trace\Config.h.


If you’re attempting to use Unreal Insights on a new platform and it does not appear to be working, it may be that the platform was never added to the list, and thus the trace code is not being compiled for that platform. The fix may be as easy as adding the appropriate #define for the platform here, but it’s possible the insights has not been previously compiled for that platform and some more work may be required.

Thanks for this! I’ve been enjoying the tool for personal testing, but I have some questions when it comes to using Unreal Insights remotely.

It has been my experience so far that: 1) Unreal Insights must be opened before an instance of the project is launched in order to connect. 2) Stopping tracing using Trace.Stop and then starting again has the effect of thereafter only storing trace data on the local machine, while no longer sending any data to the viewer application on my machine.

It would be nice to be able to stop/start tracing either from within the game instance or from the viewer application while still maintaining the link between the two. It’s not the end of the world though, as I can take the normal approach of embedding the tracing commands as command line arguments, and then essentially tracing continuously throughout the game from the beginning.

This is where my questions come in. Because the trace files get very large very fast, I am wondering the following: 1) If there is a live connection between the game and viewer app, is any trace data being stored on the game’s local computer (even in a temp directory)? 2) What do I need to move around on my end, in order to not be writing potentially up to 100GB of data to my C drive SSD in one session? For example, is there a temp folder where the data will be stored temporarily as it’s coming into my viewer app that I can move/redirect to another drive, and/or can I move the Unreal Insights application itself to my other drive?

I want to ensure that the minimum amount of trace data gets written onto the computer of someone who is sending that data to me while testing, and also minimize the amount of that data that gets written to my C drive. If that means moving all of Unreal Engine to the D drive, that shouldn’t be too much of an issue.

Sorry for rambling, thanks so much!