Download

Profiling on Device with Unreal Insights

Aug 9, 2021.Knowledge

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.

Network
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 !defined(UE_TRACE_ENABLED) # if !UE_BUILD_SHIPPING && !IS_PROGRAM # if PLATFORM_WINDOWS || PLATFORM_UNIX || PLATFORM_APPLE || PLATFORM_SWITCH || PLATFORM_ANDROID || PLATFORM_HOLOLENS # define UE_TRACE_ENABLED 1 # endif # endif #endif

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.