Android* Target Analysis from the Command Line

User Guide

Intel® VTune™ Profiler User Guide

Download PDF

ID 766319

Date 11/07/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-FD31DC31-1ECF-4360-AAD2-7C3258524826

View Details

Android* Target Analysis from the Command Line

Use the Intel® VTune™ Profiler to collect data on a remote Android application from the host system (remote usage mode) via command line interface (vtune) and view the analysis result locally from the command line or GUI.

You may run the following analysis types on Android systems:

Hotspots analysis (user-mode sampling mode)
Hardware event-based sampling analysis types
Custom analysis

Configure and Run Performance Analysis on Android System

Remote data collection using the vtune 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:

Launch your application on the target device.

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
...

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
On the development host, run vtune to collect data.

By default, the vtune 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>./vtune -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 Profiler 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, uarch-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 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.
Optional: You can send pause and resume commands during collection from another console window, for example:
```
host>./vtune -C pause -r tachyon_r001
```
```
host>./vtune -C resume -r tachyon_r001
```
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:
```
vtune -r tachyon_r001 -C stop
```

NOTE:

You may use the Command Line... option in the VTune Profiler graphical interface to automatically generate a command line for an analysis configuration selected in the GUI.

Hotspots Analysis (User-Mode Sampling)

In this mode, you can:

Run analysis without root access (although, root access is required for Java* analysis)
Run the 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).

Example

This example runs Hotspots analysis on target Android system.

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

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 Profiler 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 Profiler GUI:
1. Collect results:
```
host>./vtune -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/vtune/results/localhost.1762*.jit system_wide_r000/data.0
```

Examples

Example 1: Microarchitecture 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>./vtune -collect uarch-exploration -target-system=android -r tachyon_r@@@ -target-process com.intel.tbb.example.tachyon

Example 2: Call Stack Analysis

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

host>./vtune -collect hotspots -knob sampling-mode=hw -knob enable-stack-collection=true -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>./vtune -collect hotspots -knob sampling-mode=hw -target-system=android -duration=60 -r system_wide_r@@@

Example 4: Unplugged Mode Collection

This example configures the 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>./vtune --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 Profiler 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>./vtune -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:

vtune -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, import the result to the VTune Profiler GUI and explore the Microarchitecture Explorationdata.

Parent topic: Command Line Usage Scenarios

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® VTune™ Profiler User Guide

Android* Target Analysis from the Command Line

Configure and Run Performance Analysis on Android System

Hotspots Analysis (User-Mode Sampling)

Example

Event-Based Sampling Analysis

Examples

Custom Analysis

See Also