Skip to content

Most visited

Recently visited

navigation

Capture a GPU Trace

In this document

See also

Dependencies and prerequisites

  • OpenGL ES 2.0 or 3.1
  • Android Studio 2.2 or higher
  • Latest available GPU Debugging tools
  • Android hardware device connected through USB (phone, tablet, Android TV, or Android Auto)
  • USB Debugging in Developer Options enabled on the device
  • Project set to debuggable
  • adb integration enabled through Tools > Android > Enable ADB Integration

Note: The GPU Debugger has been removed from Android Studio as of version 2.3. An open-source, standalone version of the tool is available on GitHub.

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:

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.
    4. 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.

    5. 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.
  5. 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.

  6. 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.
    3. The Graphics Trace dialog appears in Android Studio.

      The Waiting For Debugger dialog appears on the device.

  7. In the Graphics Trace dialog, optionally change the GPU trace file name (without an extension), and then click Trace.
  8. 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.

  9. Interact with your app on the hardware device.
  10. 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.

  11. To end the GPU trace, in the Graphics Trace dialog, click Stop.
  12. The trace opens in the GPU Debugger.

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

  13. To take another GPU trace, you can run your app again.
  14. 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.
  3. The Captures window appears.

  4. Open the GFX Trace folder.
  5. Double-click the trace file to view it in the GPU Debugger.
  6. 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.
  4. Android Studio typically places GPU trace files in the AndroidStudioProjects/project-name/captures/ directory.

  5. Open the GFX Trace folder.
  6. Double-click the trace file to view it in the GPU Debugger.
  7. The GPU Debugger appears.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)