Generate a headless capture

When integrating performance analysis into continuous integration, capturing data without having the host tool connected or a user manually controlling the GUI is often required. To capture data without the Streamline host tool connected, use the streamline_me.py script in headless mode.

Before you begin

  • Install Python 3.8, or later, to run the provided streamline_me.py script.

  • Add the path to the Python3 directory to your PATH environment variable.

  • To export a configuration containing the counters that you want to capture, follow the instructions in Configure counters and export a counter configuration file. Repeat the configuration export for each class of device you need to profile.

Procedure

  1. On the host, run the streamline_me.py Python script to set up the device for a headless data capture.

    python3 streamline_me.py --package <your_app_package> --daemon <path_to_gatord> --config <path_to_your_configuration.xml> --headless <output.apc.zip>

    The script is in the following directory:

    <install_directory>/streamline/gator/

    Use the following command-line arguments:

    --package

    The Android package name of the application that you want to profile.

    Note

    To profile a non-debuggable package, you must be running a development device with root access.

    --daemon

    The path on the host to the gatord binary to install on the device. By default, this path is the current working directory. Your installation provides two versions of gatord, in the following directories:

    • <install_directory>/streamline/bin/android/arm/ for 32-bit architectures.

    • <install_directory>/streamline/bin/android/arm64/ for 64-bit architectures.

    --config

    The path to the configuration file that you saved in the Before you begin steps.

    --headless

    The path to store the saved output file to.

    If you specify --package-activity, then the script automatically starts the activity when gator is ready to capture data. If you do not specify an activity, then you must start the activity manually in the next step. If you specify an activity, you can also specify command line arguments using --package-activity to pass an argument string. You must quote this string carefully to ensure it is correctly handled, for example:

    # Argument value with no spaces
--package-arguments "--es fileName /sdcard/example/file.txt"

# Argument value with spaces and Bash quoting
--package-arguments "--es fileName \"/sdcard/example/file with spaces.txt\""

# Argument value with spaces and PowerShell quoting
--package-arguments "--es fileName '/sdcard/example/file with spaces.txt'"

  2. If you did not use the --package-activity option you must start the application manually. Wait for the script to prepare the device, and then start the application on the target device. For example:

    adb shell am start -n <app.package.name>

  3. Wait for the script to download the data from the device, and write out the output.apc.zip file.

    The script stops automatically when it detects that the application is no longer running.

  4. To view the data in the Streamline GUI, start the host application and import the APC file into the Streamline Data view.

Next steps

Analyze the data. For more information about how to analyze performance with Streamline, see Analyze your capture in the Arm Streamline User Guide.