Intel® VTune™ Amplifier XE and Intel® VTune™ Amplifier for Systems Help

Collecting Data on Android* Systems from the Command Line

Note

Remote analysis on Android* systems is supported by the Intel® VTune™ Amplifier for Systems, part of the Intel® System Studio.

Intel® VTune™ Amplifier enables you to collect data on a remote Android application from the host system (remote usage mode) via command line interface (amplxe-cl) and view the analysis result locally from the command line or GUI. You may run the following analysis types on Android systems:

Configuring and Running a Performance Analysis on Android System

Remote data collection using the amplxe-cl command running on the host is very similar to the native collection on the target except that the target-system option is added to the command line.

Prerequisites: Make sure to Preparing a Target Android* System for Remote Analysis and your Preparing an Android* Application for Analysis for analysis.

To run an analysis on an Android device:

  1. Launch your application on the target device.

  2. Find out <pid> or <name> of the application running on remote Android system. For example, you can use adb shell ps command for the purpose:

    adb shell ps
    ...
    root   2956 2   0      0     c1263c67 00000000 S kworker/u:3
    u0_a34 8485 174 770232 54260 ffffffff 00000000 R com.intel.tbb.example.tachyon
    shell  8502 235 2148   1028  00000000 b76bcf46 R ps
    ... 
  3. Optional: If you have several Android devices, you may set the ANDROID_SERIAL environment variable to specify the device you plan to use for analysis. For example:

    export ANDROID_SERIAL= emulator-5554 or export ANDROID_SERIAL= 10.23.235.47:5555

  4. On the development host, run amplxe-cl to collect data.

    By default, the amplxe-cl utility is located in the following directory:

    Use the following syntax to run an analysis:

    host>./amplxe-cl -target-system=android:deviceName -<action> <analysis_type> [-duration <duration_value>][-r <result_path>] [-search-dir=<search_dir>] [-source-search-dir=<source_search_dir>] - <target_application>

    where:

    • deviceName is the name of your Android device, for example: Medfield2B3E703C . If you do not specify the name of the device, the VTune Amplifier uses the default device specified with adb. You do not need to specify the device name if you set the ANDROID_SERIAL environment variable before the collection.
    • <action> is the action to perform the analysis (collect or collect-with)

    • <analysis_type> is a predefined analysis type, such as hotspots, advanced-hotspots, general-exploration, and so on

    • <duration_value> is the duration in seconds

    • <result_path> is a PATH/name of the directory where a result is stored

    • <search_dir> is a path to search for binary files used by your Android application

    • <source_search_dir> is a path to search for source files used by your Android application

    • <target_application> is an application to analyze. The command option depends on analysis target type:
      • To specify an application (a native Linux* application running on Android) or a script to analyze, enter the path to the application or the script on your host system.

        Note

        This target type is not supported for the Basic Hotspots analysis of Android applications.

      • To specify an Android application package to analyze, enter the name of the Android package installed on a remote device.
      • To specify a particular process to attach to and analyze, use the -target-process command to specify application by process name or the -target-pid command to specify the application by process PID.
      • To profile your Android system, do not specify target application.

        Note

        System-wide analysis is possible on rooted devices only.

  5. Optional: You can send pause and resume commands during collection from another console window, for example:

    host>./amplxe-cl -C pause -r tachyon_r001
    host>./amplxe-cl -C resume -r tachyon_r001
  6. If you do not specify analysis duration, you can stop analysis by pressing Ctrl-C or sending the stop command from another console on the host development system:

    $ amplxe-cl -r tachyon_r001 -C stop

Note

You may use the Command Line... option in the VTune Amplifier for Systems graphical interface to automatically Generating Command Line Configuration from GUI for an analysis configuration selected in the GUI.

User-mode Sampling and Tracing (Basic Hotspots) Analysis

In this mode, you can:

Example

This example runs Basic Hotspots analysis on target Android system.

host>./amplxe-cl -collect hotspots -target-system=android -r tachyon_r@@@ -- com.intel.tbb.example.tachyon

Event-Based Sampling Analysis

In this mode, you can:

The following event-based sampling analysis types are supported by the VTune Amplifier for Systems on Android systems:

Analysis Type

Command Line Name

Advanced Hotspots Analysis

advanced-hotspots

General Exploration Analysis

general-exploration

Memory Access Analysis

memory-access

CPU/GPU Concurrency Analysis

cpugpu-concurrency

System Overview Analysis

system-overview

To associate JITed Java functions to samples in the system-wide event-based sampling, you have the following two options:

Examples

Example 1: General Exploration Analysis

This example launches specified Android package and collects a complete list of events required to analyze typical client applications running on the 4th Generation Intel Core processor.

host>./amplxe-cl -collect general-exploration -target-system=android -r tachyon_r@@@ -target-process com.intel.tbb.example.tachyon

Example 2: Call Stack Analysis

By default, the VTune Amplifier does not collect stack data during hardware event-based sampling. To enable call stack analysis, use the collection-detail=stack-sampling knob. For example:

host>./amplxe-cl -collect advanced-hotspots -knob collection-detail=stack-sampling -target-system=android -r tachyon_r@@@ -target-process com.intel.tbb.example.tachyon

Example 3: System-wide Data Collection

To analyze performance of your target application and all other processes running on the Android system, use the --duration option and do not specify an analysis target.

host>./amplxe-cl -collect advanced-hotspots -target-system=android -duration=60 -r system_wide_r@@@

Example 4: Unplugged Mode Collection

This example configures the Basic Hotspots analysis for the application on an Android system that will be launched after disconnecting the device from the USB cable or a network:

host>./amplxe-cl --collect hotspots --target-system=android -unplugged-mode -r quadrant_r@@@ --target-process com.intel.fluid

Custom Analysis

Use the -collect-with option to configure VTune Amplifier to run a custom user-mode sampling and tracing (runss) or event-based sampling (runsa) analysis and take other than default configuration options. For example, to run a custom event-based sampling analysis, use the -collect-with option and specify required event counters with the -knob event-config option as follows:

host>./amplxe-cl -collect-with runsa -target-process com.intel.tbb.example.tachyon -r system_wide_r001 -knob collection-detail=stack-sampling [-event-mux] -knob event-config=CPU_CLK_UNHALTED.REF_TSC:sa=1800000,CPU_CLK_UNHALTED

Note

To display a list of events available on the target PMU, enter:

$ amplxe-cl -collect-with <collector> -target-system=android:deviceName -knob event-config=? <target_application>

You can take any counter that the Performance Monitoring Unit (PMU) of that processor supports. Additionally, you can enable multiple counters at a time. Each processor supports only a specific number of counters that can be taken at a time. You can take more events than the processor supports by using the -event-mux option, which will round robin the events you specified on the available counters in that processor.

Note

Typically, you are recommended to use analysis types with the predefined sets of counters. Use of specific counters is targeted for advanced users. Please note that names of some counters may not exactly correspond to the analysis scope provided with these counters.

After collecting these counters, Importing Results in the VTune Amplifier GUI of the VTune Amplifier for Systems and explore the Interpreting General Exploration Datadata.

See Also