Profile an Android application

Overview Before you begin Configure your device Connect Streamline to your device Choose a counter template Capture a profile Analyze your capture Next steps
Multiple Pages

Overview

This tutorial describes how to use Streamline to capture a profile of a debuggable application running on an unrooted Android device with a  MaliTM GPU. Follow the steps in each section to set up your environment, connect to the target device and capture a profile to analyze.

You can also view these steps in this video:

Choose Next to browse through the steps as you work through them, or choose Single Page to view all the steps on one page.

Before you begin

On your host machine:

  1. Download and install the Arm Mobile Studio package appropriate to your host platform (Windows, Linux, or macOS).
  2. Install Android Debug Bridge (ADB). ADB is available with the Android SDK platform tools, which are installed as part of Android Studio, or you can download them separately here. Streamline uses ADB to connect to your device.
  3. Edit your PATH environment variable to add the path to the Android SDK platform tools directory. This means that you can run ADB from any location on your machine, and that Streamline can automatically find ADB when attempting to connect to your device.

    If you decide not to do this, you must add the path to ADB in your Streamline preferences, under External Tools:
    Settting the path to ADB in Streamline

Configure your device

On your device:

  1. Ensure Developer Mode is enabled, then enable USB Debugging using Settings > Developer options.
  2. Connect the target to the host through USB. 
  3. Run the adb devices command on the host to check that connection is successful. If successful, this command returns the ID of your target.
    adb devices
List of devices attached
ce12345abcdf1a1234       device
    You should also be able to run adb shell without issues.
  4. Install a debuggable application:
    • For Unity applications, select the Development Build option in Unity's Build Settings when building your application.
    • If you're not using Unity, ensure your application is marked as debuggable in the Android application manifest (see more on how to do this in the Android Studio documentation).

Connect Streamline to your device

Follow these steps to launch Streamline and select your device.

  1. Launch Streamline:
    1. On Windows, from the Start menu, navigate to the Arm Mobile Studio folder, and select the Streamline shortcut.
    2. On macOS, go to the <install_dir>/streamline folder, and double-click the Streamline.app file.
    3. On Linux, go to the <install_dir>/streamline folder, and run the Streamline file:
      cd <install_dir>/streamline
       ./Streamline
  2. Use the Start tab in Streamline to select your device. Select Android (adb) then select your device from the list. The Configure Application list will show the applications installed on the selected device. Choose the application you want to profile from the list.

    Note: If you don't see your device listed, check that you have set up ADB correctly, as described in before you begin, and that your device is configured correctly.

  3. Before starting the capture, choose Configure Counters to choose a counter template.

Choose a counter template

Counter templates are pre-defined sets of performance counters that enable you to perform an initial performance review of how the CPU and GPU behave when you run your application. Choose the most appropriate template for the GPU in your target device.

  1. From the Start tab, open the Counter configuration dialog by selecting Configure Counters.
    Streamline's configure counters button
  2. Choose Add counters from a template Add counters from a template button to see the list of available templates. 

    Streamline's counter configuration dialog
  3. Choose a counter template appropriate for the target GPU in your target device. The number of counters in the template that your target device supports is shown next to each template. For example, here, 34 of the 38 available counters in the Mali Midgard template are supported in the connected device. 
    Choosing a counter template in Streamline

    For detailed descriptions of all of the available counters for each Mali GPU, refer to the Mali GPU counter reference.

  4. Save your changes.
  5. Optionally, select Advanced Settings from the Start tab, to set additional capture options, including the sample rate and the capture duration.
    Streamline's advanced settings button
    Refer to Capture options in the Arm Streamline User Guide for more details.

Capture a profile

  1. Select Start Capture.
    Streamline start capture button
  2. Specify the name and location of the capture file that Streamline will create when the capture is complete.
  3. The application will start on the device, and the charts in Streamline will update in real time to show the data being captured. Below the charts is a list of running processes in your application with their CPU usage.
  4. Unless you specified a capture duration in Advanced Settings, click Stop capture to end the capture . Streamline saves the capture file in the location you specified previously and then prepares the capture for analysis. When complete, the capture appears in the Timeline view.
  5. Select the Switch and manage templates button  and select the same counter configuration template that you chose to create the capture.
    Select the counter template for your target GPU

Analyze your capture

Analyze the data in Streamline's Timeline view to see how the GPU and CPU in the device handled your application. The charts area is populated with the performance counter activity for the counters in the selected template. Below the charts area is the details panel, which provides further metrics from your capture. Both the charts and details panel are aligned on the timeline.

For detailed descriptions of all of the available counters for each Mali GPU, refer to the Mali GPU counter reference.

  1. Control the granularity of the data by selecting the time unit. For example, if you choose 50ms, every color-coded unit in the details panel represents data captured during a 50ms window.
  2. Hover over a chart to see the values at that point on the timeline.
    Hover over a chart in Streamline to see the values
  3. Click anywhere on the timeline and drag the handles on the cross-section marker to select a range of time to investigate more closely. The information shown in the details panel when in Processes and Samples modes updates to show data for the window of time you have defined.
    Cross-section marker

    Note: If you define a region of time with the Cross-section marker, then change the view to a larger time unit where the Cross-section marker border cannot sit precisely, the border is displayed as a blurred line.

  4. Unlike the filter controls, moving and expanding the Cross-section marker does not affect the data in the other report views. To do this, use the calipers to set the required time region. Drag the calipers to the required time region, or right-click on the timeline and select Set Left Caliper or Set Right Caliper. When you move the calipers, the Call Paths, Functions, and Code views update to show information for the selected region. 
    Select a time region with the calipers

Refer to Android performance triage with Streamline to learn more about how to interpret the charts in Streamline. For more information about the different views and capabilities of Streamline, see Analyze your capture in the Arm Streamline User Guide.

Disconnect Streamline from your target

  1. IMPORTANT: On the host, switch back to the terminal running the gator_me.py script and press any key to terminate the script. The script kills all processes that it started and removes gatord from the target.
  2. Unplug your device from your host machine.