Upload Quest Debug Files for Crash Analytics

If you have the debuggable library files (also known as debug symbol files) for your Quest app, you can upload them to see symbolicated stack traces in the Crash Analytics dashboard.

Uploading Debug Symbol Files from Unity

The OVR Platform Tool in Unity is configured to automatically upload debug symbols for your app whenever you upload a .APK file to a release channel. The Debug Symbols Directory defaults to the standard symbol path for your project built with IL2CPP scripting backend. If your project is built using the Mono scripting backend, you can select the relevant symbol path. For more information, see Upload App to Oculus Store.

Unity OVR Platform Tool with Symbol Directory Path

Uploading Debug Symbol Files from Unreal Engine

The Oculus Platform Tool in Unreal Engine is configured to automatically upload debug symbols for your app whenever you upload a .APK file to a release channel. The Symbol Directory Path defaults to the standard symbol path where UE4 stores symbols for your project. You can clear the path setting if you don’t want to upload symbols. Or, if your symbols are stored elsewhere, you can specify a new path for where your symbolicated libUE4.so file is located. For more information, see Upload Apps to Oculus from the Unreal Editor.

UE4 Oculus Platform Tool with Symbol Directory Path

Uploading Debug Symbol Files from the Oculus Platform Command Line Utility

You can use the Oculus Platform Command Line Utility (CLI) to upload debug symbols. You can upload symbols together with your app, or you can upload symbols separately and attach them to an existing app build.

Where are the Debug Symbol Files?

Apps packaged for upload to an Oculus release channel are stripped of debug symbolics. However, versions of your library files that include debug symbols are still located on your file system. They typically match the filename pattern *.so, *.sym.so, or *.dbg.so, and these are the files we use in Crash Analytics to symbolicate stack traces. For example, if the library your project creates is called libunity.so, the symbolicated version of it might have the same name of libunity.so, or it might be named libunity.sym.so or libunity.dbg.so.

Important:

Don't change the name of the debug symbol files. Crash analytics uses filename matching to match the library name in your app with the matching debug symbol file ending in .so, .sym.so, or .dbg.so. These are the only allowable filename extensions for debug symbol files.

If these debug symbol files have been deleted since the last time you built the project, it is sometimes possible to rebuild them provided that you have changed absolutely nothing in the project since the time you uploaded the app into a release channel. Even a small difference can create a mismatch between an uploaded app binary and the rebuilt debug symbol files, which can result in missing symbols in stack traces.

Caution:

Do not close the Unity Editor until after you copy all the debug symbol files to a permanent location, because closing the editor might delete them.

EngineLocation of debug symbol files
NativeprojectFolder/obj/local/armeabi-v7a/
UnityIL2CPP projects: projectFolder\Temp\StagingArea\libs\armeabi-v7a\
mono projects: C:\Program Files\Unity\Editor\Data\PlaybackEngines\AndroidPlayer\Variations\mono\Release\Symbols\armeabi-v7a\
UnrealprojectFolder\Binaries\Android\projectName_Symbols_v1\projectName-arm64

Uploading Debug Symbol Files for an Existing Quest Binary

You can use the Oculus Platform Command Line Utility (CLI) to attach debug symbol files to a Quest app previously uploaded to a release channel. This is useful if this is the first time you’ve had the opportunity to upload debug symbol files for your app but you don’t want to force all your users to update to a new app version just so that you can get symbolicated crash analytics.

You need to have the app ID and app secret or user token credentials needed to complete the CLI commands, and also the Build ID of the binary the debug symbol files belong to.

To obtain the Build ID:

  1. Go to the app’s Overview page from the Oculus Developer Dashboard.

  2. From the Recently Uploaded Builds list, find the specific build you want to attach symbols to, and then click its version number. The Build Details page appears.

  3. From the Details tab, copy the Build ID of this binary for later use.

    Build ID in the Build Details page

CLI Syntax

ovr-platform-util upload-debug-symbols --parent <buildId> --app_id <Id> --app_secret <app-secret> --debug_symbols_dir <dirPath> --debug-symbols-patternfilenamePattern

--parent <buildID> Specifies the build ID of the binary to attach the debug symbol files.

--debug_symbols_dir <dirPath> Specifies the path of the directory that contains the debug symbol file or files.

--debug-symbols-pattern <filenamePattern> Specifies a file name pattern that matches the filenames of all the debug symbol files. You may use an asterisk to indicate a wildcard, for example: *.sym.so

Uploading Debug Symbol Files for a New Quest Binary

You can use the Oculus Platform CLI to attach debug symbol files while uploading a new Quest app to a release channel. The syntax is the same as uploading a new Quest app to a channel by itself, but you also append the following two parameters to specify the debug symbol file path and filename pattern:

--debug_symbols_dir <dirpath> Specifies the path of the directory that contains the debug symbol file or files.

--debug-symbols-pattern <filenamePattern> Specifies a file name pattern that matches the filenames of all the debug symbol files. You may use an asterisk to indicate a wildcard, for example: *.sym.so

Example

ovr-platform-util upload-quest-build --app_id 12345678901234 --token ABCDEF1234567890abcdef1234567890  --apk c:\myproject\app\build\outputs\apk\myApp.apk --channel store --debug_symbols_dir c:\myproject\obj\local\armeabi-v7a\ --debug-symbols-pattern *.sym.so

Verifying Uploaded Debug Symbols

Any debug symbol files you upload appear in the Build Details page of your app binary, under the Expansion Files tab.

Debug Symbol Files listed under Expansion Files tab