Android GPU Inspector (AGI) is currently in open beta. Learn more.

Getting started with Android GPU Inspector

Android GPU Inspector (AGI) allows you to conduct system and frame traces to better understand how well your graphics application is performing.

AGI supports profiling apps that use Vulkan or OpenGL ES graphics. OpenGL ES support is obtained by translating OpenGL ES to Vulkan by using ANGLE.

Use this guide to get started using AGI to capture traces.

Android device requirements

Using AGI with an Android device requires the following:

  • A supported Android device (listed on this page) running Android 11 or higher.

  • A USB cable.

  • To enable AGI to install its own APK, the device must have adb debugging enabled and be accessible through adb. If the Install via USB option is present, turn it on.

  • Your app must be debuggable; the debuggable attribute in the Android manifest of the app must be set to true. This attribute enables proper instrumentations from the graphics driver. For Vulkan applications, this attribute enables AGI to add its own Vulkan layer when the application starts.

    <application [...] android:debuggable="true">
    

If your app uses Vulkan natively, AGI also requires the following:

  • Your app must not report any warning or error when it runs with the Vulkan validation layers enabled. Fix any Vulkan validation error before profiling. The frame profiler is designed with the assumption that the app uses the Vulkan API correctly. Invalid use of the Vulkan API is considered undefined behavior.

  • If you are using beta GPU drivers, include the following piece of metadata the <application> tag of the APK manifest:

    <meta-data
              android:name="com.android.graphics.developerdriver.enable"
              android:value="true" />
    

Supported devices

Android emulators are not supported. The following Android devices (running Android 11 or higher) are supported by AGI in open beta:

Device name GPU name
Google Pixel 4 (standard and XL) Qualcomm® Adreno™ 640
Google Pixel 4a Qualcomm® Adreno™ 618
Google Pixel 4a 5G Qualcomm® Adreno™ 620
Google Pixel 5 Qualcomm® Adreno™ 620
Samsung Galaxy S10 series Qualcomm® Adreno™ 640 and Arm® Mali™ G76
Samsung Galaxy S20 series Qualcomm® Adreno™ 650 and Arm® Mali™ G77
Samsung Galaxy Note 10 series Qualcomm® Adreno™ 640 and Arm® Mali™ G76
Samsung Galaxy Note 20 series Qualcomm® Adreno™ 650 and Arm® Mali™ G77
Samsung Galaxy S21 series Qualcomm® Adreno™ 660 and Arm® Mali™ G78

Device validation

AGI requires a compatible GPU driver. To ensure it provides valid profiling data, AGI runs a validation check the first time you connect a new device, which takes about ten seconds. After passing the check, the device can be used to profile Android applications.

Do not disturb the device while AGI device support validation is in progress. This may cause the device to fail validation checks. If a device fails validation but is set up correctly, you can retry the support validation by re-selecting the device.

Validating your device is a one-time step, and results are cached for future use of AGI. However, AGI will run validation again if the device setup changes (such as if the GPU driver or the version of Android are updated).

If a device is listed as a supported device as shown on this page, you can expect AGI to pass validation. If the device is not listed, its GPU driver is most likely incompatible with AGI.

If your device is supported but fails validation

Make sure you've fulfilled all Android requirements and host computer requirements described in the preceding section, and that the device is properly connected to the host computer by a USB cable.

If all of the requirements are properly fulfilled, this may be a bug. Please file an issue in our GitHub repository describing the behavior you're seeing.

If your device isn't supported

We periodically update our supported device page with devices that support AGI. We are working with our OEM partners to add support to more devices.

Please file an issue in our GitHub repository to request support for a device. We will connect you to the OEM in question.

Host computer requirements

Profiling your app using a host requires one of the following:

  • Windows: Windows 7 or higher.

  • macOS: El Capitan (10.11) or higher.

  • Linux: Java 64-bit JDK or JRE 8 (or newer) is required, and Ubuntu Trusty Tahr (14.04 or higher) is recommended.

Download and install AGI

Download and install the latest asset for Windows, macOS, or Linux from the latest release posted on GitHub.

If you'd like to try an unstable developer releases, we publish them frequently. You can download and install the agi-dev-releases developer build from GitHub.

Capture a trace

Before capturing a trace, make sure you've fulfilled all Android requirements and host computer requirements described previously on this page.

Configure AGI to your app

Capturing a trace involves first configuring AGI to associate with the app you want to profile. When that's done, you can conduct a system trace or frame trace.

To configure AGI with your app:

  1. Using a USB cable, connect a supported Android device to your host computer, and make sure adb debugging is enabled.

  2. Launch AGI.

    The first time you launch AGI, it presents a Welcome screen that prompts you for the path location of the adb executable. AGI will save these settings in the .agic file in your HOME folder. (If you've already done this, you can go to step 3.)

    Welcome screen
    Figure 1: Welcome screen
    1. Enter the path to the adb executable in Path to adb field. The checkboxes following this field are optional.

    2. Click Get Started.

    The main launch screen displays.

    Welcome window
    Figure 2: Android GPU Inspector main launch screen
    Capture System Profile dialog
    Figure 3: Capture System Profile dialog (setup)
  3. In the main launch screen, click Capture a new trace. This displays the Capture System Profile dialog.

  4. Select the Android device you want to capture on. If it doesn't display in the Device list, click the reload arrow next to the menu to refresh the list.

  5. Under the Application section, select the app you want to trace. If there is only one activity in the package, you can simply select the package instead of the Activity.

    AGI comes with a sample Vulkan app. You would perform the following steps to set up that app.

    1. Next to the Application field, click the ... button.

      This shows the Select an Application to Trace window, which displays a list of apps that are traceable on the selected device.

    2. In the filter text box, type gapid to filter down applications to the ones that contain "gapid" in their package name.

    3. Expand the package, select com.google.android.gapid.VkSampleActivity, and click OK.

      This returns you to the Capture System Profile window, with the Application field populated by the app you selected.

  6. In the Application section, leave the other fields empty.

  7. Click OK.

Now you're ready to use AGI to perform a system and frame profile traces.

Perform a system profile trace

To perform a system profile trace:

  1. Make sure you have configured AGI with your app as described in the previous section.

  2. In the AGI launch screen, click Capture a new trace to display the Capture System Profile dialog.

  3. From the Type list, select System profile.

  4. Under the Start and Duration section, set Start at to Manual, and Duration to 2.

  5. In the Trace Options section, click Configure. This displays a dialog showing trace configuration options.

    Capture Config dialog
    Figure 4: Configuration options in Capture System Profile dialog
  6. In the trace options configuration dialog, select the profiling data you want to capture.

  7. In the GPU section, click Select.

    This displays a dialog showing a selection of counters to choose from.

    Counter config
    Figure 5: Selecting counters
  8. In the counter selection dialog, click default to select the set of default counters, and click OK to return the trace options configuration dialog.

  9. Click OK to return to the main Capture System Profile dialog.

  10. In the Output section, select an Output Directory to choose a location for the capture files. The File Name field should be auto-filled, but you can edit it if you like.

  11. Once you've completed these steps, click OK. This starts the selected app on the Android device, and creates a pop-up window with a Start button.

  12. Click the Start button to start the performance capture, and wait a couple of seconds for the trace to terminate.

  13. When the capture is completed, click Open Trace. This leads to a view similar to systrace.

    System profile trace
    Figure 6: System profile trace

In addition to the data available in systrace, AGI also shows GPU performance information. The GPU Queue section shows when GPU commands are submitted and when the GPU actually starts work. The GPU Counters shows various performance counters to help optimize the graphics works in the app. See Analyze a system profiler trace for details.

Perform a frame profile trace

To perform a frame profile trace:

  1. Make sure you have configured AGI with your app as described in a previous section.

  2. In the AGI launch screen, click Capture a new trace to display the Capture System Profile dialog.

  3. From the Type list, select Vulkan or OpenGL on ANGLE depending on which Graphics API your app is using. Make sure you're choosing the right one, otherwise AGI won't capture any graphics commands.

  4. Under the Start and Duration section, set Start at to Manual. You can also select Beginning to take the trace at app startup, Frame to take the trace a given frame, and Time to take the trace after a given number of seconds. Frame profiler traces are always one frame long.

  5. In the Output section, select an Output Directory to choose a location for the capture files. The File Name field should be auto-filled, but you can edit it if you like.

  6. Optional: Some apps spawn a different process that does all the graphics processing. To capture that process, specify its name.

  7. Once you've completed these steps, click OK. This starts the selected app on the Android device, and creates a pop-up window with a Start button.

  8. Click the Start button to start the graphics capture, and wait a couple of seconds for the trace to terminate.

  9. Once the capture is completed, click Open Trace. This shows a view that shows the trace analysis. Each panel is described in detail in the Reference Docs section.

    Frame profile trace
    Figure 7: Frame profile trace

Validate Vulkan on Android

If your app isn't already set up to run with Vulkan validation layers, you can use the following commands to force it to run with the validation layers shipped in the AGI apk (named com.google.android.gapid.<abi>):

app_package=<YOUR APP PACKAGE NAME HERE>
abi=arm64v8a # Possible values: arm64v8a, armeabi-v7a, x86

adb shell settings put global enable_gpu_debug_layers 1
adb shell settings put global gpu_debug_app ${app_package}
adb shell settings put global gpu_debug_layer_app com.google.android.gapid.${abi}
adb shell settings put global gpu_debug_layers VK_LAYER_KHRONOS_validation

To disable validation layers:

adb shell settings delete global enable_gpu_debug_layers
adb shell settings delete global gpu_debug_app
adb shell settings delete global gpu_debug_layers
adb shell settings delete global gpu_debug_layer_app

File a bug

If you experience any apparent issues with AGI, you can file an issue through GitHub.