This topic describes how to perform system profiling and frame profiling on your Android app using Android GPU Inspector (AGI).

This quickstart is intended for developers that are familiar with graphics development on Android.

Computer requirements

The computer that runs AGI must meet these requirements:

• One of the following operating systems is required:

  • Windows: Windows 7 or higher.

  • macOS: El Capitan (10.11) or higher.

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

• The adb command line tool.

Download and install AGI

Download and install AGI for your operating system.

Android app requirements

This section describes the requirements for the Android app that is being profiled:

• Your Android 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 have Vulkan validation layers enabled. If they aren't enabled, you can run the following commands to force your app to run with the validation layers that are included in the AGI apk (com.google.android.gapid.<abi>):

  app_package=<YOURAPPPACKAGENAMEHERE>
  abi=arm64v8a# Possible values: arm64v8a, armeabi-v7a, x86
  adbshellsettingsputglobalenable_gpu_debug_layers1
  adbshellsettingsputglobalgpu_debug_app${app_package}
  adbshellsettingsputglobalgpu_debug_layer_appcom.google.android.gapid.${abi}
  adbshellsettingsputglobalgpu_debug_layersVK_LAYER_KHRONOS_validation
  

  When you're done profiling can disable these validation layers with the following commands:

  adbshellsettingsdeleteglobalenable_gpu_debug_layers
  adbshellsettingsdeleteglobalgpu_debug_app
  adbshellsettingsdeleteglobalgpu_debug_layers
  adbshellsettingsdeleteglobalgpu_debug_layer_app
  

• Your app must not report any warnings or errors when it runs with the Vulkan validation layers enabled. Fix any Vulkan validation error before profiling.

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

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

Android device requirements

AGI has the following Android device requirements:

• A supported Android device running Android 11 or higher.

• A USB cable.

• adb debugging must be enabled and the device must be accessible through adb. If the Install via USB option is present, enable it.

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, you can use the device to profile Android apps.

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

Validation is a one-time step for a device, 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 Android version is updated.

If a device is listed as a supported device, 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 met all Android requirements and computer requirements described in the preceding sections, and that the device is properly connected to the computer with a USB cable.

If all of the requirements are met, file a issue in our GitHub repository describing the behavior.

If your device isn't supported

We are working with our OEM partners to add support for more devices. You can file an issue in our GitHub repository to request support for a device.

Capture profiling data

The following sections describe how to capture profiling data, and open the resulting trace file so you can analyze the results.

Configure Android settings

Before you begin profiling, you must configure these Android app and device settings, which specify the app and device to profile.

1. Using a USB cable, connect your Android device to your computer.

2. Launch AGI on your computer.

   The first time you launch AGI, it displays the Welcome screen, which prompts you for the path to the adb executable. AGI saves these settings in the .agic file in your HOME folder. If you've already done this, you can skip this step.

   Welcome screen

3. Enter the path to the adb executable in the Path to adb field. The checkboxes following this field are optional.

4. Click Get Started to display the launch screen.

   AGI launch screen

5. In the launch screen, click Capture a new trace. This displays the Capture A New Trace dialog. Alternatively, you can click the Capture System Profile trace button.

   Capture A New Trace dialog

6. In the Device and Type section, select the Android device you want to profile. If it's not displayed in the Device list, click the reload arrow to refresh the list.

7. In the Application section, select the app you want to profile. If there is only one activity in the package, you can select the package instead of the activity.

   AGI includes a sample Vulkan app. To use the sample app instead of your own, perform these steps:

   1. Click the ... button next to the Application field.

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

   2. In the Filter text box, type gapid to only display applications that contain gapid in their package name.

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

      This returns you to the Capture A New Trace dialog, with the Application field populated by the app you selected.

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

9. Click OK.

Now you're ready to use AGI to perform system and frame profiling.

Profile a system

To profile a system, perform these steps:

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

2. In the Type list, select System profile.

3. In the Start and Duration section, set Start at to Manual, and Duration to 2.

4. In the Trace Options section, click Configure. This displays a list of profiling options.

   Capture Config dialog

5. Select the profiling data you want to capture.

6. In the GPU section, click Select.

   This displays a list of counters to select.

   Counter config

7. Click default to select the set of default counters, and click OK to return the profiling options.

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

9. In the Output section, select an Output Directory to store the the trace files that are generated during profiling. The File Name field should be auto-filled, but you can also edit it.

10. Click OK. This starts the selected app on the Android device, and displays a pop-up window with a Start button.

11. Click the Start button to start capturing profiling data, and wait a couple of seconds for the process to finish.

12. Click Open Trace. The initial view that is displayed is similar to systrace.

    System profile trace

    In addition to the data available in systrace, AGI also shows GPU performance information. For more information about viewing system profiling data, see View an AGI system profile.

For information about additional settings, see system profiling options.

Profile a frame

To profile an individual frame from your app, perform these steps:

1. In the AGI launch screen, click Capture a new trace to display the Capture A New Trace dialog. Alternatively, you can click the Capture Frame Profile trace button.

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

3. In the Start and Duration section, set Start at to Manual. If you clicked the Capture Frame Profile trace button, this step is already completed.

4. In the Output section, select an Output Directory to store the trace files. The File Name field should be auto-filled, but you can also edit it.

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

6. Click OK. This starts your app on the Android device, and displays a pop-up window with a Start button.

7. Click the Start button and wait a few of seconds for profiling to complete.

8. Click Open Trace to view the profiling data. For information about each pane in the Frame Profiler UI, see the Frame profiling overview.

For information about additional settings, see frame profiling options.