Collecting Data on Android* Systems from the Command Line

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 prepare a target Android* system and your application 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:

   • On Windows*: <install_dir>\bin{32,64}

   • On Linux*: <install_dir>/bin{32,64}

   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

User-mode Sampling and Tracing (Basic Hotspots) Analysis

In this mode, you can:

• Run analysis without root access (although, root access is required for Java* analysis)

• Run the Basic Hotspots analysis (if a target process or PID is specified) to identify functions that take the most time to execute (hotspots)

• Explore call stacks

• View C/C++ generated functions/source

• (If installed) Automatically obtain Java function names for functions that have been JITed and drill down to either JIT assembly or Java source or DEX Byte Code

  Note

  Java analysis is not supported for the 4th Generation Intel® Core™ processors (based on Intel microarchitecture code name Haswell).

Event-Based Sampling Analysis

In this mode, you can:

• Use hardware event-based sampling analysis types with event groups predefined by Intel architects

• View C/C++ generated functions/source

• Explore call stacks (if a target process or PID is specified)

• Analyze performance system wide (if call stack analysis is disabled)

• (If installed) Automatically obtain Java function names for functions that have been JITed and drill down to either JIT assembly or Java source or DEX Byte Code

  Note

  Java analysis is not supported for the 4th Generation Intel® Core™ processors (based on Intel microarchitecture code name Haswell) or systems using ART.

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

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

• Specify -target-process Proccess.Name for the process you are interested in similar to how you do this for the event-based call stack collection.

• For any process you are interested in, copy the JIT files for the PID of that process into the data.0 directory, and re-resolve the results in the VTune Amplifier GUI:

  1. Collect results:

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

  2. Find PID of interesting processes:

     adb shell ps | [grep MyApp]
     u0_a79 1762 141 575912 75468 ffffffff 4006f2ef Scom.android.MyApp

  3. Copy all jit files for processes you are interested in to the data.0 directory:

     adb pull /data/amplxe/results/localhost.1762*.jit system_wide_r000/data.0

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

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.

After collecting these counters, import the result to the VTune Amplifier GUI and explore the General Explorationdata.