This topic describes how to perform
[system profiling](https://developer.android.com/agi/sys-trace/system-profiler) and
[frame profiling](https://developer.android.com/agi/frame-trace/frame-profiler)
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)](https://releases.ubuntu.com/14.04/)
    is recommended.

- The [adb command line tool](https://developer.android.com/studio/command-line/adb).

## Download and install AGI

[Download](https://developer.android.com/agi#downloads) 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](https://developer.android.com/guide/topics/manifest/application-element#debug)
  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](https://developer.android.com/ndk/guides/graphics/validation-layer)
  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=<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

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

      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

- Your app must not report any warnings or errors when it runs with the
  [Vulkan validation layers](https://developer.android.com/ndk/guides/graphics/validation-layer)
  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](https://developer.android.com/agi/supported-devices) running
  [Android 11 or higher](https://developer.android.com/about/versions).

- 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](https://developer.android.com/agi/supported-devices), 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](https://developer.android.com/agi/start#android-reqs) and
[computer requirements](https://developer.android.com/agi/start#host-reqs) 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](https://github.com/google/agi/issues) 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](https://github.com/google/agi/issues) 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](https://developer.android.com/static/images/games/agi/get-started.png) **Figure 1: 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](https://developer.android.com/static/images/games/agi/agi-launcher.png) **Figure 2:** Android GPU Inspector main 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](https://developer.android.com/static/images/games/agi/capture-new-trace.png) **Figure 3: 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](https://developer.android.com/static/images/games/agi/capture-config.png) **Figure 4:** The profiling options in the **Capture System Profile** 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](https://developer.android.com/static/images/games/agi/counter-config.png) **Figure 5:**Selecting counters.
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](https://developer.android.com/studio/profile/systrace).

    ![System profile trace](https://developer.android.com/static/images/games/agi/system-profile.png) **Figure 6:**The System Profiler UI.

    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](https://developer.android.com/agi/sys-trace/system-profiler-gui).

For information about additional settings, see
[system profiling options](https://developer.android.com/agi/sys-trace/system-profiler#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](https://developer.android.com/agi/frame-trace/frame-profiler#frame-views).

For information about additional settings, see
[frame profiling options](https://developer.android.com/agi/frame-trace/frame-profiler#profiling_options).