1# Examples of using simpleperf to profile Android applications
2
3## Table of Contents
4
5- [Examples of using simpleperf to profile Android applications](#examples-of-using-simpleperf-to-profile-android-applications)
6  - [Table of Contents](#table-of-contents)
7  - [Introduction](#introduction)
8  - [Profile a Java application](#profile-a-java-application)
9  - [Profile a Java/C++ application](#profile-a-javac-application)
10  - [Profile a Kotlin application](#profile-a-kotlin-application)
11- [Profile via app_api](#profile-via-app_api)
12
13## Introduction
14
15Simpleperf is a native profiler used on Android platform. It can be used to profile Android
16applications. Its documentation is [here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/doc/README.md).
17Instructions of preparing your Android application for profiling are [here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/doc/README.md#Android-application-profiling).
18This directory is to show examples of using simpleperf to profile Android applications. The
19meaning of each directory is as below:
20
21    ../scripts/                  -- contain simpleperf binaries and scripts.
22    SimpleperfExamplePureJava/   -- contains an Android Studio project using only Java code.
23    SimpleperfExampleWithNative/ -- contains an Android Studio project using both Java and C++ code.
24    SimpleperfExampleOfKotlin/   -- contains an Android Studio project using Kotlin code.
25    CppApi/                      -- contains an Android Studio project using c++ app_api to record.
26    JavaApi/                     -- contains an Android Studio project using Java app_api to record.
27
28It can be downloaded as below:
29
30```sh
31$ git clone https://android.googlesource.com/platform/system/extras
32$ cd extras/simpleperf/demo
33```
34
35The testing environment:
36
37```
38Android Studio 3.2
39test device: Android O (Google Pixel 2)
40test device: Android N (Google Nexus 6P)
41Please make sure your device having Android version >= N.
42```
43
44## Profile a Java application
45
46Android Studio project: SimpleExamplePureJava
47
48steps:
491. Build and install the application:
50
51```sh
52# Open SimpleperfExamplesPureJava project with Android Studio,
53# and build this project successfully, otherwise the `./gradlew` command below will fail.
54$ cd SimpleperfExamplePureJava
55
56# On windows, use "gradlew" instead.
57$ ./gradlew clean assemble
58$ adb install -r app/build/outputs/apk/app-profiling.apk
59```
60
612. Record profiling data:
62
63```sh
64$ cd ../../scripts/
65# app_profiler.py collects profiling data in perf.data, and binaries on device in binary_cache/.
66$ python app_profiler.py -p com.example.simpleperf.simpleperfexamplepurejava
67```
68
693. Show profiling data:
70
71```sh
72# report_html.py generates profiling result in report.html.
73$ python report_html.py --add_source_code --source_dirs ../demo --add_disassembly
74```
75
76## Profile a Java/C++ application
77
78Android Studio project: SimpleExampleWithNative
79
80steps:
811. Build and install the application:
82
83```sh
84# Open SimpleperfExamplesWithNative project with Android Studio,
85# and build this project sucessfully, otherwise the `./gradlew` command below will fail.
86$ cd SimpleperfExampleWithNative
87
88# On windows, use "gradlew" instead.
89$ ./gradlew clean assemble
90$ adb install -r app/build/outputs/apk/profiling/app-profiling.apk
91```
92
932. Record profiling data:
94
95```sh
96$ cd ../../scripts/
97# app_profiler.py collects profiling data in perf.data, and binaries on device in binary_cache/.
98$ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative
99```
100
1013. Show profiling data:
102
103```sh
104# report_html.py generates profiling result in report.html.
105$ python report_html.py --add_source_code --source_dirs ../demo --add_disassembly
106```
107
108## Profile a Kotlin application
109
110Android Studio project: SimpleExampleOfKotlin
111
112steps:
1131. Build and install the application:
114
115```sh
116# Open SimpleperfExamplesOfKotlin project with Android Studio,
117# and build this project sucessfully, otherwise the `./gradlew` command below will fail.
118$ cd SimpleperfExampleOfKotlin
119
120# On windows, use "gradlew" instead.
121$ ./gradlew clean assemble
122$ adb install -r app/build/outputs/apk/profiling/app-profiling.apk
123```
124
1252. Record profiling data:
126
127```sh
128$ cd ../../scripts/
129# app_profiler.py collects profiling data in perf.data, and binaries on device in binary_cache/.
130$ python app_profiler.py -p com.example.simpleperf.simpleperfexampleofkotlin
131```
132
1333. Show profiling data:
134
135```sh
136# report_html.py generates profiling result in report.html.
137$ python report_html.py --add_source_code --source_dirs ../demo --add_disassembly
138```
139
140# Profile via app_api
141
142Android Studio project: CppApi and JavaApi
143
144steps:
1451. Build and install the application:
146
147```sh
148# Open CppApi project with Android Studio,
149# and build this project sucessfully, otherwise the `./gradlew` command below will fail.
150$ cd CppApi
151
152# On windows, use "gradlew" instead.
153$ ./gradlew clean assemble
154$ adb install -r app/build/outputs/apk/debug/app-debug.apk
155```
156
1572. Prepare recording environment.
158
159```sh
160$ cd ../../scripts/
161$ python api_profiler.py prepare
162```
163
1643. Run the CppApi app.
165
166```sh
167# launch the app via cmdline, can also launch it on device.
168# A profiling file is generated each time running the app.
169$ adb shell am start simpleperf.demo.cpp_api/.MainActivity
170```
171
1724. Collect profiling data.
173
174```sh
175$ python api_profiler.py collect -p simpleperf.demo.cpp_api
176```
177
1785. Report profiling data.
179
180```sh
181$ python report_html.py -i simpleperf_data/* --aggregate-by-thread-name
182```
183