Sep 20, 2021

Get Started with the Unity Profiler & Profile Analyzer Data on Quest

Cristiano Ferreira Blog Hero Image

Attaching the Unity Profiler and saving out trace data to help track CPU hotspots is a very reliable and easy process on the Oculus Quest. With the addition of the Unity Profile Analyzer⁠, these tools combined offer a variety of ways that you can help shave off precious milliseconds from the CPU and set up a solid regression testing workflow. The objective of this article is to show you how to capture profiling data from your application running on the Quest and then show you how you can ingest the profiler data into the Profile Analyzer to pinpoint spikes, hotspots and performance regressions with the compare mode. For further information about these tools be sure to check out Unity’s documentation at the end of this article.

Building and Capturing

Build out your APK with Development Build checked within the build menu.

Install the APK on your Quest

Make sure that your Quest is on the same network as your machine running the Unity editor

Get your IP address and add it to the target list in the Unity profiler

Open command prompt

Enter ‘adb shell ip addr show wlan0’

Take note of your device’s ip address and save it

In Unity, open the Unity profiler

Window > Analysis > Profiler

On the top pane where you see Record, Deep Profile, Profile Editor, Editor, etc. Click the Editor dropdown and click <Enter IP> then paste in the IP address you grabbed in the previous step and hit Connect.

After you’ve added the IP, you can run the game on your Quest and connect by selecting the IP you entered in the same dropdown. It may take a few seconds to connect, but right after you’ll see profiling data begin to populate the various profilers you have selected. Data is kept in a circular buffer up to x frames where x is provided as a setting. Be sure to immediately pause capture after you’ve encountered the scenario that you’d like to investigate.

Important note: There’s LOTS of overhead to capturing profiling data, so be sure to discount this information when getting profiling numbers and looking at frame time. Unity will show you the estimated overhead which is captured in a profiling marker at the end of the frame slice.

For raw frame time, we recommend using the OVRMetrics Tool without ever connecting the profiler.

OVRMetricsTool:

Download Page

Usage instructions:

Install the APK and run the app with adb shell am start omms://app to configure it.

If you want to get timing info on sub-sections of custom functions, you can use Unity’s profiler markers⁠ to delimit beginning / end code regions with a custom string to identify the section.

Include UnityEngine.Profiling namespace

Add Profiler.BeginSample(“My code section”); before the region you want to have added to the profiler collection.

Add Profiler.EndSample(); after the region you want to collect profiling info on.

Saving / Loading Profiler Data

Once you’ve captured enough frames and want to save out a play session, just click the save button in the profiler. This will save the *.pdata file that you can load back in at any time via the load button next to it.

The Unity Profiler data can be opened on other machines, so it’s good to store some tied to various versions on an internal server for regression testing later on.

Using the Unity Profile Analyzer

The Unity Profile Analyzer is useful because it pulls a set of frames captured in your Profiler trace and performs statistical analysis on them, generating useful info for each function such as min, median, mean, max timings (with clustered plotting on the side) as well as total call counts across the pulled frames and the count mean (the average count per frame). This tool can also diff 2 sets of profiling data which will provide info on performance regressions or improvements. Finding the highest median/mean timings on functions with high call counts are the best way to improve overall performance. Additionally, the functions with a huge discrepancy between mean/median time and max time will help you quickly identify spikes to alleviate. Just sort by the max column and do your checking!

Installing the Profile Analyzer Package

Select Window > Package Manager

Click the Packages: My Assets dropdown and select Packages: Unity Registry to show available packages

Scroll to Profile Analyzer and click Install

Profile Analyzer will now show up under Window > Analysis > Profile Analyzer

Profile Analyzer General Usage / Tips

With your profiling data loaded into the Unity Profiler, open Profile Analyzer and click the Pull Data button to pull existing frame data from the open Unity Profiler

When it loads you’ll get a breakdown of your heaviest functions in median time

Remember to verify the call count isn’t just a one-off for heavy functions if you want to work on consistently heavy functions frame by frame

Here is an overview of the tool window

Tips

You can drill into only user scripts (removing engine layer functions) by selecting Depth slice: 4. If you look at the Unity profiler in timeline mode, you can correlate the callstack depth to make a selection here - user scripts appear in blue and are the 4th level down. This is a quick way to see if your specific logic scripts are heavy by themselves.

You can do the same with rendering data to see how much time the CPU is taking to prepare opaques vs transparents, etc. for example

On the right side, you can find the highlighted function’s performance range histogram - you can find the exact frame the max timing was found on and then go back to the profiler to select that frame to analyze contributing factors.

Profile Analyzer Compare Mode

When you have profiler data loaded into the tool, click the save button to save a profile analyzer data file.

Pull in new data you want to compare to and save that in the same fashion.

Under mode, click Compare button (default is Single)

Load in both profile analyzer files (left and right)

Tip: Name them Before_<Filename> and After_<Filename> for easy differentiation

You’ll get a breakdown of timings on a per-function basis between the two frame sets, as long as names and labels weren’t changed between build versions.