Capture a GPU Trace

Note: The GPU Debugger is Beta in Android Studio 2.2.

After you set a certain run/debug configuration option and then run an app project, Android Studio launches a dialog that lets you start a GPU trace. Before starting the GPU trace, Android Studio either determines the activity to launch, or asks you for it. GPU tracing always starts at the beginning of your app. If you want to trace a later portion of your app, you should modify your app to launch directly into that later portion.

GPU trace files

After you capture a GPU trace, Android Studio opens it in the GPU Debugger. The trace file appears in the Captures window, so you can open it any time you want. The GPU trace list in the Captures window is project-specific. Android Studio stores the trace file in the project captures/ directory.

You can also open a GPU trace file stored on your computer, even if it's not listed in the Captures window for a particular project.

Trace libraries

GPU tracing doesn't modify your APK. Instead, it launches your app in debug mode and, at startup, attaches the trace libraries to the running process. Android Studio copies the trace libraries into the files directory for the app on the device. (If needed, you can discover the files directory by using the getFilesDir() method.) Once loaded, the trace libraries capture OpenGL ES commands from your app and send them back to Android Studio so you can analyze them. When you’re finished tracing the app, you can optionally delete the trace libraries.

Tips for successfully capturing a GPU trace

Many apps load a large number of graphics at the beginning when you start them. When you first begin a GPU trace for an app that’s just starting up, you need to be patient while it loads this information. After loading, the tool starts to capture frames.

The performance and memory of your development computer can influence how large of a GPU trace you can display in the GPU Debugger. If your computer has trouble displaying a large GPU trace, try capturing a smaller trace. For a typical Android Studio configuration, we recommend keeping the capture to a maximum of about 1000 frames and 500,000 calls.

To increase the amount of memory that Android Studio is allowed to use, follow these steps:

1. Select Help > Edit Custom VM Options.
2. In the studio.vmoptions file, change the -Xmx option to -Xmx2G for 32-bit or -Xmx4G for 64-bit computers.
3. Save the file, and then restart Android Studio.

For more information, see Customize your VM options.

Restrictions

Note the following GPU tracing behaviors:

• After you enable GPU tracing in your current run/debug configuration, Android Studio traces your app every time you run it using that run/debug configuration. If you want to stop GPU tracing, you should select a different run/debug configuration or disable the option.
• You can’t take a GPU trace while debugging the app. If you select Run > Debug, Android Studio disables GPU tracing automatically.

Capture a GPU trace for an Android Studio project

To capture a GPU trace for an app in an Android Studio project, follow these steps:

1. Open your Android Studio project.
2. Set the run/debug configuration settings for the GPU Debugger as follows:
1. Select Run > Edit Configurations.
2. Click the Profiling tab.
3. Make sure that Capture GPU Commands is selected so you can perform GPU tracing.

If the GPU Tools Missing dialog appears, you need to install the GPU Debugging tools as follows. In the dialog, click OK. In the Install Missing Components dialog, click Finish to complete the installation.

4. In the Run/Debug Configurations dialog, click OK.

Tip: You can define separate run/debug configurations for tracing, running, and debugging your app. This helps you to quickly switch between operations.

3. Connect an Android hardware device to your USB port.
4. If the Allow USB Debugging dialog appears on the device, click OK.

This dialog typically appears on your home screen (for example, after you log in), not on the boot screen. If you don’t allow USB debugging, Android Studio shows your device as OFFLINE, and you can’t perform a GPU trace.

5. Run your project on the hardware device as follows:
   1. Select Run > Run, or click Run .
   2. In the Select Deployment Target dialog, select the hardware device, and then click OK.

   The Graphics Trace dialog appears in Android Studio.

   The Waiting For Debugger dialog appears on the device.

6. In the Graphics Trace dialog, optionally change the GPU trace file name (without an extension), and then click Trace.

The Graphics Trace dialog appears. First, the tool attaches the trace library. Next, it starts the trace.

If your device doesn’t support GPU tracing, you receive an error:

The GPU debugger does not currently support tracing on this device.

7. Interact with your app on the hardware device.

As long as the MB value in the Graphics Trace dialog keeps rising while you interact with the app, the GPU trace is proceeding normally.

8. To end the GPU trace, in the Graphics Trace dialog, click Stop.

The trace opens in the GPU Debugger.

Android Studio creates a GPU trace file with an extension of .gfxtrace.

9. To take another GPU trace, you can run your app again.

You can view your saved GPU traces in the Captures window. See View a saved GPU trace file.

View a saved GPU trace file

After you perform a GPU trace, Android Studio automatically stores it so you can view it again. It places the file in the captures/ directory of the project where you took the GPU trace. You can open a GPU trace file from the Captures window for a project, or by selecting the file on disk.

To open a GPU trace file from the Captures window, follow these steps:

1. Open an Android Studio project.
2. Select View > Tools Windows > Captures.

The Captures window appears.

3. Open the GFX Trace folder.
4. Double-click the trace file to view it in the GPU Debugger.

The GPU Debugger appears.

To open a GPU trace file stored on your development computer, follow these steps:

1. Open an Android Studio project.
2. Select File > Open.
3. In the Open File or Project dialog, select the GPU trace, and then click OK.

Android Studio typically places GPU trace files in the AndroidStudioProjects/project-name/captures/ directory.

4. Open the GFX Trace folder.
5. Double-click the trace file to view it in the GPU Debugger.

The GPU Debugger appears.