Oculus Go Development

On 6/23/20 Oculus announced plans to sunset Oculus Go. Information about dates and alternatives can be found in the Oculus Go introduction.

Oculus Quest Development

All Oculus Quest developers MUST PASS the concept review prior to gaining publishing access to the Quest Store and additional resources. Submit a concept document for review as early in your Quest application development cycle as possible. For additional information and context, please see Submitting Your App to the Oculus Quest Store.

Logcat

The logcat logging utility is a command-line tool included with the Android SDK that is used to display OS and application log messages. During development, logcat is essential for determining what an app and the Android OS are doing while the app is running on a device.

Logcat is included with Android Studio. See Android Development Software Setup for information on configuring the Android SDK for Oculus development.

See Basic Performance Stats through Logcat for information on interpreting logcat VrApi logs.

Overview

Logcat can be used while an app is running on a device to display logged messages from the app and the Android OS. Android-related messages include system messages, such as stack traces thrown on errors. Messages related to Oculus apps, which are tagged with VrApi, provide information on app performance every second. This information can be used to identify performance problem areas, bottlenecks, and to determine crash causes. Logcat can also be used to retrieve logs from apps that have recently crashed in order to potentially identify causes.

Advantages of logcat include its familiarity to Android developers, low overhead, and engine agnosticism. While it provides only basic information, logcat is useful as a tool for general triage on Android apps.

Collect Oculus VrApi Logs with Logcat

The following sections describe how to set up logcat, collect Oculus VrApi logs from an app running on a device, and possibly view logs from crashes that occurred while logcat was not in use.

Preparation

The Oculus device to be used with logcat must be in Developer Mode as described in Device Setup. To install Android Studio, which includes logcat, see Android Development Software Setup.

When using logcat, the Oculus device must be connected to your computer via Android Debug Bridge (ADB), which is also installed with Android Studio. This can be through either a USB or Wi-Fi connection. For information on how to connect to a device using ADB, see ADB.

Basic Usage

To use logcat, connect the Android device via USB or Wi-Fi, launch an OS shell, and type:

adb logcat

If the device is connected and detected, the output logs will immediately begin displaying to the shell. In most cases, this raw output is too verbose to be useful. Logcat solves this by supporting filtering by tags. To see only a specific tag, use:

adb logcat -s <tag>

This example will show only output with the Oculus “VrApi” tag:

adb logcat -s VrApi

In the native VrAppFramework code, messages can generally be printed using the LOG() macro. In most source files this is defined to pass a tag specific to that file. Log.h defines a few additional logging macros, but all resolve to calling __android_log_print().

For information on interpreting VrApi performance statistics returned by logcat, see Logcat for Basic Performance Stats.

Using Logcat to Determine the Cause of a Crash

Logcat will not necessarily be running when an application crashes. Fortunately, it keeps a buffer of recent output, and in many cases a command can be issued to logcat immediately after a crash to capture the log that includes the backtrace for the crash:

adb logcat > crash.log

Simply issue the above command, give the shell a moment to copy the buffered output to the log file, and then end ADB (Ctrl+C in a Windows command prompt or macOS terminal prompt). Then search the log for “backtrace:” to locate the stack trace beginning with the crash.

If too much time as elapsed and the log does not show the backtrace, a full dump state of the crash should still exist. Use the following command to redirect the entire dump state to a file:

adb shell dumpstate > dumpstate.log

Copying the full dump state to a log file usually takes significantly longer than simply capturing the currently buffered logcat log, but it can provide additional information about the crash.

Getting a Better Stack Trace

The backtrace in a logcat capture or dump state generally shows the function where the crash occurred, but does not provide line numbering. To get more information about a crash, the Android Native Development Kit (NDK) must be installed. When the NDK is installed, the ndk-stack utility can be used to parse the logcat log or dump state for more detailed information about the state of the stack. To use ndk-stack, issue the following:

ndk-stack -sym <path to symbol file> -dump <source log file> > stack.log

For example, this command uses the symbol information for Oculus 360 Photos to output a more detailed stack trace to a file named stack.log, using the backtrace found in crash.log.:

ndk-stack -sym VrNative\Oculus360Photos\obj\local\armeabi-v7a -dump crash.log > stack.log