Meta Developers

For any app developer, it’s very important that their app does not have compromised performance. Poor performance can be a result of inefficient use of resources such as graphics, CPU, memory, heat, and battery drainage.

MQDH bundles several tools such as OVR Metrics Tool, Perfetto, Performance Analyzer, and logs from Logcat to closely monitor and analyze performance-specific metrics. There’s no need to wear the headset and interact with the tool as you can slide a toggle in MQDH to control the tool’s visibility in the headset.

Install OVR Metrics Tool

OVR Metrics Tool provides vital performance metrics via an overlaid graph on an app that’s running in the headset.

From the Device Manager tab, under Device Actions, click Install next to OVR Metrics Tool.
On Device Manager, under Device Actions slide the Metrics HUD toggle to launch the OVR Metrics Tool on the headset.
Turn on the Metrics Recording toggle to record metrics on the Meta Quest headset.
Click ... next to Metrics Recording to view recorded metrics files, which contain rich graphs with performance data across more than 30 stats.

Uninstall OVR Metrics

To uninstall OVR Metrics from the headset, under Apps, look for com.oculus.ovrmonitormetricsservice, click ... for more options, and click Uninstall.

Use Performance Analyzer

Meta Quest Developer Hub (MQDH) includes Performance Analyzer, a real-time metrics monitor for Meta Quest headsets. Performance Analyzer includes a configurable assortment of metrics graphs, a filterable synchronized Logcat stream, and the ability to launch Perfetto traces. There is also a switch to disable casting during profiling to decrease overhead.

Performance Analyzer Use Cases

Performance Analyzer offers a wide view of system processes and activity while an app is running. It offers the ability to set metrics thresholds that, when hit, will cause Performance Analyzer to throw a flag on the timeline. This feature can be useful in spotting bottlenecks and areas where there might be issues or opportunities for performance improvement.

In addition, Perfetto is available from Performance Analyzer. Perfetto is an Android system-wide profiling tool that provides information on system events such as scheduling activity in addition to app-level instrumentation for apps that integrate with Perfetto’s TrackEvent instrumentation or ATrace.

Setup

To use Performance Analyzer, connect to a Meta Quest headset via ADB. Once connected, press the play button at the top of the screen and metrics will start populating the timeline on the Performance Analyzer tab. Run an app to get metrics for that app.

Performance Analyzer Features

The following sections describe how to use the various features of Performance Analyzer.

Disable Casting to Reduce Overhead

Performance Analyzer includes a window in the lower-right corner that displays low-latency video output from the attached Meta Quest headset. You can disable this casting functionality to reduce overhead and offer more precise performance metrics. Use the Casting toggle above the video window to disable casting.

View and Customize the Utilization Graphs

Performance Analyzer includes 12 modules of utilization graphs that can be included on the left side of the screen. The modules can be enabled and disabled using the Modules drop-down at the top of the list of metrics on the left. Most modules include multiple metrics. The modules include the following:

VRCs
CPU
GPU
GPU Memory Access
GPU Render Pipeline Stats
Vertex Shading Stats
Fragment Shading Stats
GPU Misc. Shader Unit Stats
Frame Rate
Rendering Config
Timings
Memory

At the top of the screen, press the play button to start displaying metrics. If you have been clicking performance flags or panning and pausing through the timeline to investigate something, click the Live button to bring the graph back to real-time metrics.

Performance Flags

In the upper-right corner of the screen, there is a gear icon that leads to Performance Settings. Here you can specify a threshold number for any metric, and when a metric rises above or falls below that number, a performance flag notification is displayed in the Flags pane on the right side of the screen. Clicking a flag takes you to the moment on the timeline when the threshold event occurred. To return back to the real-time metrics feed, click the Live button at the top of the screen.

View and Search Logcat Logs

At the bottom of Performance Analyzer is a Logs section that displays real-time logs generated from Android’s Logcat messages matching the current filter when enabled with the up arrow button. Logcat messages provide important information such as system messages, stack traces when a garbage collection occurs, and messages that you’ve added to the app. However, keep in mind that Logcat messages have a high CPU overhead, and enabling them can interfere with profiling.

You can adjust the log type using the Type list and use the Regex toggle to filter through results using regular expression syntax.

Use the Perfetto Integration

The MQDH Perfetto integration provides information on system events such as scheduling activity in addition to app-level instrumentation for apps that integrate with Perfetto’s TrackEvent instrumentation or ATrace. It offers a wide view of system processes and additional metrics on the same timeline as the app’s performance profile. It can also map functions by using the OVRPlugin to call the OS directly and get more insight into various GPU counters and metrics at a high level to better correlate where performance issues might be. It is a replacement for Systrace that supports a larger selection of events, longer traces, and adds support for counters.

Perfetto traces can be launched from Performance Analyzer as well as from the Device Manager, under Device Actions. For a detailed guide on using the Perfetto integration in MQDH, including how to interpret a trace and suggestions on other tools to try, see How to Take Perfetto Traces with Meta Quest Developer Hub.

Before running a Perfetto trace, adjust the appropriate settings. Trace Analysis by Perfetto can be found above the Flags pane. Click … > Perfetto settings to access the settings.

Commercial game engines such as Unity and Unreal Engine only emit ATrace instrumentation, so it is a requirement to configure ATrace Categories and ATrace Apps.

Perfetto settings include the following:

Perfetto Settings Preference - Setting this to Custom allows you to provide a custom Perfetto TraceConfig in JSON form. The remainder of the settings apply to the General preference.
Auto open trace - Automatically opens traces in a new browser window after they have been recorded.
Trace duration - Allows you to indicate an unlimited length or to specify a fixed duration in ms.
Trace buffer size - Allows you to specify the size of the trace buffer.
GPU Trace buffer size - Allows you to specify the size of the GPU trace buffer.
CPU Scheduling - Enables detailed tracking of CPU scheduling events.
ATrace Categories - Comma-separated list of ATrace categories to track. These are events that might be in many apps.
ATrace Apps - List of ATrace apps to track. These are apps where events are turned on. You can choose to track all ATrace apps or provide a comma-separated list of apps to track.
TrackEvent - Record TrackEvent data for running applications. For more information on TrackEvent data, see the Perfetto Track events documentation.
XR Runtime Metrics - Enables the recording of XR Runtime metrics.
GPU Metrics - Provides GPU metrics.
GPU Render Stage Trace - Track GPU render stage traces.
TrackEvent Config - TrackEvent data to be recorded. All fields are comma separated. For more information on TrackEvent configuration, see the Perfetto Track events documentation.
- Process Name Filter - Filter track events only from processes that match this name.
- Process Name Filter Regex - Filter track events only from processes that match this regular expression.
- Disabled Categories - Event categories disabled for tracking.
- Enabled Categories - Event categories enabled for tracking. All categories are enabled when empty.
- Disabled Tags - Tags disabled for tracking.
- Enabled Tags - Tags enabled for tracking. All tags are enabled when empty.
Callstack Sampling Config - Controls what app to sample, and when/how often the sampling is triggered. For more information, see Callstack sampling.

ATRACE APPS FIELD

Developers using Unity and Unreal Engine, and any other developers using ATrace events, must enter their package name in the **ATrace Apps** field to get detailed information from Perfetto. In general, it is strongly recommended that all developers fill this field.

After configuring the settings, do the following to run a Perfetto trace:

Under Trace Analysis by Perfetto, click Record.
Run your app and get to a section you would like to test.
Once finished, stop recording by clicking the stop icon under Trace Analysis by Perfetto. MQDH opens the trace on the Perfetto site in a new browser window.
To open traces later, click ... > Recorded Traces. From there you can also rename traces, open their location in the file explorer, and delete all traces.

Perfetto traces are also saved in the File Manager, under MQDH Files > Perfetto. For more information on reading Perfetto traces after taking them, see our guide.

Here are some other tools that might be of interest to users of OVR Metrics Tool, Performance Analyzer, and Perfetto:

RenderDoc Meta Fork - Meta fork of the RenderDoc graphics debugging tool with added access to low-level GPU profiling data from Meta Quest’s Snapdragon 835, Meta Quest 2’s Snapdragon XR2, and Meta Quest Pro’s Snapdragon XR2+ chips, specifically information from the tile renderer.
Use Simpleperf for CPU Profiling - Command-line Android development tool that samples an application at a given frequency to determine where the CPU is consuming time and where other performance-related hardware events are occurring.
Use ovrgpuprofiler for GPU Profiling - Command-line tool included on Meta Quest headsets that accesses real-time metrics and GPU profiling data in a convenient, low-friction manner.
Get Started with the Unity Profiler and the Unity Profile Analyzer - Unity specific profiler that pulls a set of frames captured in a trace and performs analysis on them, generating useful info for each function.