Debian Codegraph @

simpleperf/doc/README.md

raw
1 # Simpleperf
2
3 Simpleperf is a native profiling tool for Android. It can be used to profile
4 both Android applications and native processes running on Android. It can
5 profile both Java and C++ code on Android. It can be used on Android L
6 and above.
7
8 Simpleperf is part of the Android Open Source Project. The source code is [here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/).
9 The latest document is [here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/doc/README.md).
10
11 ## Table of Contents
12
13 - [Introduction](#introduction)
14 - [Tools in simpleperf](#tools-in-simpleperf)
15 - [Android application profiling](#android-application-profiling)
16 - [Prepare an Android application](#prepare-an-android-application)
17 - [Record and report profiling data](#record-and-report-profiling-data)
18 - [Record and report call graph](#record-and-report-call-graph)
19 - [Report in html interface](#report-in-html-interface)
20 - [Show flame graph](#show-flame-graph)
21 - [Record both on CPU time and off CPU time](#record-both-on-cpu-time-and-off-cpu-time)
22 - [Profile from launch](#profile-from-launch)
23 - [Parse profiling data manually](#parse-profiling-data-manually)
24 - [Android platform profiling](#android-platform-profiling)
25 - [Executable commands reference](#executable-commands-reference)
26 - [How simpleperf works](#how-simpleperf-works)
27 - [Commands](#commands)
28 - [The list command](#the-list-command)
29 - [The stat command](#the-stat-command)
30 - [Select events to stat](#select-events-to-stat)
31 - [Select target to stat](#select-target-to-stat)
32 - [Decide how long to stat](#decide-how-long-to-stat)
33 - [Decide the print interval](#decide-the-print-interval)
34 - [Display counters in systrace](#display-counters-in-systrace)
35 - [The record command](#the-record-command)
36 - [Select events to record](#select-events-to-record)
37 - [Select target to record](#select-target-to-record)
38 - [Set the frequency to record](#set-the-frequency-to-record)
39 - [Decide how long to record](#decide-how-long-to-record)
40 - [Set the path to store profiling data](#set-the-path-to-store-profiling-data)
41 - [Record call graphs](#record-call-graphs-in-record-cmd)
42 - [Record both on CPU time and off CPU time](#record-both-on-cpu-time-and-off-cpu-time-in-record-cmd)
43 - [The report command](#the-report-command)
44 - [Set the path to read profiling data](#set-the-path-to-read-profiling-data)
45 - [Set the path to find binaries](#set-the-path-to-find-binaries)
46 - [Filter samples](#filter-samples)
47 - [Group samples into sample entries](#group-samples-into-sample-entries)
48 - [Report call graphs](#report-call-graphs-in-report-cmd)
49 - [Scripts reference](#scripts-reference)
50 - [app_profiler.py](#app_profiler-py)
51 - [Profile from launch of an application](#profile-from-launch-of-an-application)
52 - [run_simpleperf_without_usb_connection.py](#run_simpleperf_without_usb_connection-py)
53 - [binary_cache_builder.py](#binary_cache_builder-py)
54 - [run_simpleperf_on_device.py](#run_simpleperf_on_device-py)
55 - [report.py](#report-py)
56 - [report_html.py](#report_html-py)
57 - [inferno](#inferno)
58 - [pprof_proto_generator.py](#pprof_proto_generator-py)
59 - [report_sample.py](#report_sample-py)
60 - [simpleperf_report_lib.py](#simpleperf_report_lib-py)
61 - [Answers to common issues](#answers-to-common-issues)
62 - [Why we suggest profiling on android >= N devices](#why-we-suggest-profiling-on-android-n-devices)
63 - [Suggestions about recording call graphs](#suggestions-about-recording-call-graphs)
64 - [How to solve missing symbols in report](#how-to-solve-missing-symbols-in-report)
65 - [Bugs and contribution](#bugs-and-contribution)
66
67 ## Introduction
68
69 Simpleperf contains two parts: the simpleperf executable and Python scripts.
70
71 The simpleperf executable works similar to linux-tools-perf, but has some specific features for
72 the Android profiling environment:
73
74 1. It collects more info in profiling data. Since the common workflow is "record on the device, and
75 report on the host", simpleperf not only collects samples in profiling data, but also collects
76 needed symbols, device info and recording time.
77
78 2. It delivers new features for recording.
79 a. When recording dwarf based call graph, simpleperf unwinds the stack before writing a sample
80 to file. This is to save storage space on the device.
81 b. Support tracing both on CPU time and off CPU time with --trace-offcpu option.
82 c. Support recording callgraphs of JITed and interpreted Java code on Android >= P.
83
84 3. It relates closely to the Android platform.
85 a. Is aware of Android environment, like using system properties to enable profiling, using
86 run-as to profile in application's context.
87 b. Supports reading symbols and debug information from the .gnu_debugdata section, because
88 system libraries are built with .gnu_debugdata section starting from Android O.
89 c. Supports profiling shared libraries embedded in apk files.
90 d. It uses the standard Android stack unwinder, so its results are consistent with all other
91 Android tools.
92
93 4. It builds executables and shared libraries for different usages.
94 a. Builds static executables on the device. Since static executables don't rely on any library,
95 simpleperf executables can be pushed on any Android device and used to record profiling data.
96 b. Builds executables on different hosts: Linux, Mac and Windows. These executables can be used
97 to report on hosts.
98 c. Builds report shared libraries on different hosts. The report library is used by different
99 Python scripts to parse profiling data.
100
101 Detailed documentation for the simpleperf executable is [here](#executable-commands-reference).
102
103 Python scripts are split into three parts according to their functions:
104
105 1. Scripts used for recording, like app_profiler.py, run_simpleperf_without_usb_connection.py.
106
107 2. Scripts used for reporting, like report.py, report_html.py, inferno.
108
109 3. Scripts used for parsing profiling data, like simpleperf_report_lib.py.
110
111 Detailed documentation for the Python scripts is [here](#scripts-reference).
112
113 ## Tools in simpleperf
114
115 The simpleperf executables and Python scripts are located in simpleperf/ in ndk releases, and in
116 system/extras/simpleperf/scripts/ in AOSP. Their functions are listed below.
117
118 bin/: contains executables and shared libraries.
119
120 bin/android/${arch}/simpleperf: static simpleperf executables used on the device.
121
122 bin/${host}/${arch}/simpleperf: simpleperf executables used on the host, only supports reporting.
123
124 bin/${host}/${arch}/libsimpleperf_report.${so/dylib/dll}: report shared libraries used on the host.
125
126 [app_profiler.py](#app_profiler-py): recording profiling data.
127
128 [run_simpleperf_without_usb_connection.py](#run_simpleperf_without_usb_connection-py):
129 recording profiling data while the USB cable isn't connected.
130
131 [binary_cache_builder.py](#binary_cache_builder-py): building binary cache for profiling data.
132
133 [report.py](#report-py): reporting in stdio interface.
134
135 [report_html.py](#report_html-py): reporting in html interface.
136
137 [inferno.sh](#inferno) (or inferno.bat on Windows): generating flamegraph in html interface.
138
139 inferno/: implementation of inferno. Used by inferno.sh.
140
141 [pprof_proto_generator.py](#pprof_proto_generator-py): converting profiling data to the format
142 used by [pprof](https://github.com/google/pprof).
143
144 [report_sample.py](#report_sample-py): converting profiling data to the format used by [FlameGraph](https://github.com/brendangregg/FlameGraph).
145
146 [simpleperf_report_lib.py](#simpleperf_report_lib-py): library for parsing profiling data.
147
148
149 ## Android application profiling
150
151 This section shows how to profile an Android application.
152 Some examples are [Here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/demo/README.md).
153
154 Profiling an Android application involves three steps:
155 1. Prepare an Android application.
156 2. Record profiling data.
157 3. Report profiling data.
158
159 ### Prepare an Android application
160
161 Based on the profiling situation, we may need to customize the build script to generate an apk file
162 specifically for profiling. Below are some suggestions.
163
164 1. If you want to profile a debug build of an application:
165
166 For the debug build type, Android studio sets android::debuggable="true" in AndroidManifest.xml,
167 enables JNI checks and may not optimize C/C++ code. It can be profiled by simpleperf without any
168 change.
169
170 2. If you want to profile a release build of an application:
171
172 For the release build type, Android studio sets android::debuggable="false" in AndroidManifest.xml,
173 disables JNI checks and optimizes C/C++ code. However, security restrictions mean that only apps
174 with android::debuggable set to true can be profiled. So simpleperf can only profile a release
175 build under these two circumstances:
176 If you are on a rooted device, you can profile any app.
177
178 If you are on Android >= O, we can use [wrap.sh](#https://developer.android.com/ndk/guides/wrap-script.html)
179 to profile a release build:
180 Step 1: Add android::debuggable="true" in AndroidManifest.xml to enable profiling.
181 ```
182 <manifest ...>
183 <application android::debuggable="true" ...>
184 ```
185
186 Step 2: Add wrap.sh in lib/`arch` directories. wrap.sh runs the app without passing any debug flags
187 to ART, so the app runs as a release app. wrap.sh can be done by adding the script below in
188 app/build.gradle.
189 ```
190 android {
191 buildTypes {
192 release {
193 sourceSets {
194 release {
195 resources {
196 srcDir {
197 "wrap_sh_lib_dir"
198 }
199 }
200 }
201 }
202 }
203 }
204 }
205
206 task createWrapShLibDir
207 for (String abi : ["armeabi", "armeabi-v7a", "arm64-v8a", "x86", "x86_64"]) {
208 def dir = new File("app/wrap_sh_lib_dir/lib/" + abi)
209 dir.mkdirs()
210 def wrapFile = new File(dir, "wrap.sh")
211 wrapFile.withWriter { writer ->
212 writer.write('#!/system/bin/sh\n\$@\n')
213 }
214 }
215 }
216 ```
217
218 3. If you want to profile C/C++ code:
219
220 Android studio strips symbol table and debug info of native libraries in the apk. So the profiling
221 results may contain unknown symbols or broken callgraphs. To fix this, we can pass app_profiler.py
222 a directory containing unstripped native libraries via the -lib option. Usually the directory can
223 be the path of your Android Studio project.
224
225
226 4. If you want to profile Java code:
227
228 On Android >= P, simpleperf supports profiling Java code, no matter whether it is executed by
229 the interpreter, or JITed, or compiled into native instructions. So you don't need to do anything.
230
231 On Android O, simpleperf supports profiling Java code which is compiled into native instructions,
232 and it also needs wrap.sh to use the compiled Java code. To compile Java code, we can pass
233 app_profiler.py the --compile_java_code option.
234
235 On Android N, simpleperf supports profiling Java code that is compiled into native instructions.
236 To compile java code, we can pass app_profiler.py the --compile_java_code option.
237
238 On Android <= M, simpleperf doesn't support profiling Java code.
239
240
241 Below I use application [SimpleperfExampleWithNative](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/demo/SimpleperfExampleWithNative).
242 It builds an app-profiling.apk for profiling.
243
244 ```sh
245 $ git clone https://android.googlesource.com/platform/system/extras
246 $ cd extras/simpleperf/demo
247 # Open SimpleperfExamplesWithNative project with Android studio, and build this project
248 # successfully, otherwise the `./gradlew` command below will fail.
249 $ cd SimpleperfExampleWithNative
250
251 # On windows, use "gradlew" instead.
252 $ ./gradlew clean assemble
253 $ adb install -r app/build/outputs/apk/profiling/app-profiling.apk
254 ```
255
256 ### Record and report profiling data
257
258 We can use [app-profiler.py](#app_profiler-py) to profile Android applications.
259
260 ```sh
261 # Cd to the directory of simpleperf scripts. Record perf.data.
262 # -p option selects the profiled app using its package name.
263 # --compile_java_code option compiles Java code into native instructions, which isn't needed on
264 # Android >= P.
265 # -a option selects the Activity to profile.
266 # -lib option gives the directory to find debug native libraries.
267 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative --compile_java_code \
268 -a .MixActivity -lib path_of_SimpleperfExampleWithNative
269 ```
270
271 This will collect profiling data in perf.data in the current directory, and related native
272 binaries in binary_cache/.
273
274 Normally we need to use the app when profiling, otherwise we may record no samples. But in this
275 case, the MixActivity starts a busy thread. So we don't need to use the app while profiling.
276
277 ```sh
278 # Report perf.data in stdio interface.
279 $ python report.py
280 Cmdline: /data/data/com.example.simpleperf.simpleperfexamplewithnative/simpleperf record ...
281 Arch: arm64
282 Event: task-clock:u (type 1, config 1)
283 Samples: 10023
284 Event count: 10023000000
285
286 Overhead Command Pid Tid Shared Object Symbol
287 27.04% BusyThread 5703 5729 /system/lib64/libart.so art::JniMethodStart(art::Thread*)
288 25.87% BusyThread 5703 5729 /system/lib64/libc.so long StrToI<long, ...
289 ...
290 ```
291
292 [report.py](#report-py) reports profiling data in stdio interface. If there are a lot of unknown
293 symbols in the report, check [here](#how-to-solve-missing-symbols-in-report).
294
295 ```sh
296 # Report perf.data in html interface.
297 $ python report_html.py
298
299 # Add source code and disassembly. Change the path of source_dirs if it not correct.
300 $ python report_html.py --add_source_code --source_dirs path_of_SimpleperfExampleWithNative \
301 --add_disassembly
302 ```
303
304 [report_html.py](#report_html-py) generates report in report.html, and pops up a browser tab to
305 show it.
306
307 ### Record and report call graph
308
309 We can record and report [call graphs](#record-call-graphs-in-record-cmd) as below.
310
311 ```sh
312 # Record dwarf based call graphs: add "-g" in the -r option.
313 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative \
314 -r "-e task-clock:u -f 1000 --duration 10 -g" -lib path_of_SimpleperfExampleWithNative
315
316 # Record stack frame based call graphs: add "--call-graph fp" in the -r option.
317 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative \
318 -r "-e task-clock:u -f 1000 --duration 10 --call-graph fp" \
319 -lib path_of_SimpleperfExampleWithNative
320
321 # Report call graphs in stdio interface.
322 $ python report.py -g
323
324 # Report call graphs in python Tk interface.
325 $ python report.py -g --gui
326
327 # Report call graphs in html interface.
328 $ python report_html.py
329
330 # Report call graphs in flame graphs.
331 # On Windows, use inferno.bat instead of ./inferno.sh.
332 $ ./inferno.sh -sc
333 ```
334
335 ### Report in html interface
336
337 We can use [report_html.py](#report_html-py) to show profiling results in a web browser.
338 report_html.py integrates chart statistics, sample table, flame graphs, source code annotation
339 and disassembly annotation. It is the recommended way to show reports.
340
341 ```sh
342 $ python report_html.py
343 ```
344
345 ### Show flame graph
346
347 To show flame graphs, we need to first record call graphs. Flame graphs are shown by
348 report_html.py in the "Flamegraph" tab.
349 We can also use [inferno](#inferno) to show flame graphs directly.
350
351 ```sh
352 # On Windows, use inferno.bat instead of ./inferno.sh.
353 $ ./inferno.sh -sc
354 ```
355
356 We can also build flame graphs using https://github.com/brendangregg/FlameGraph.
357 Please make sure you have perl installed.
358
359 ```sh
360 $ git clone https://github.com/brendangregg/FlameGraph.git
361 $ python report_sample.py --symfs binary_cache >out.perf
362 $ FlameGraph/stackcollapse-perf.pl out.perf >out.folded
363 $ FlameGraph/flamegraph.pl out.folded >a.svg
364 ```
365
366 ### Record both on CPU time and off CPU time
367
368 We can [record both on CPU time and off CPU time](#record-both-on-cpu-time-and-off-cpu-time-in-record-cmd).
369
370 First check if trace-offcpu feature is supported on the device.
371
372 ```sh
373 $ python run_simpleperf_on_device.py list --show-features
374 dwarf-based-call-graph
375 trace-offcpu
376 ```
377
378 If trace-offcpu is supported, it will be shown in the feature list. Then we can try it.
379
380 ```sh
381 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative -a .SleepActivity \
382 -r "-g -e task-clock:u -f 1000 --duration 10 --trace-offcpu" \
383 -lib path_of_SimpleperfExampleWithNative
384 $ python report_html.py --add_disassembly --add_source_code \
385 --source_dirs path_of_SimpleperfExampleWithNative
386 ```
387
388 ### Profile from launch
389
390 We can [profile from launch of an application](#profile-from-launch-of-an-application).
391
392 ```sh
393 # Start simpleperf recording, then start the Activity to profile.
394 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative -a .MainActivity
395
396 # We can also start the Activity on the device manually.
397 # 1. Make sure the application isn't running or one of the recent apps.
398 # 2. Start simpleperf recording.
399 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative
400 # 3. Start the app manually on the device.
401 ```
402
403 ### Parse profiling data manually
404
405 We can also write python scripts to parse profiling data manually, by using
406 [simpleperf_report_lib.py](#simpleperf_report_lib-py). Examples are report_sample.py,
407 report_html.py.
408
409 ## Android platform profiling
410
411 Here are some tips for Android platform developers, who build and flash system images on rooted
412 devices:
413 1. After running `adb root`, simpleperf can be used to profile any process or system wide.
414 2. It is recommended to use the latest simpleperf available in AOSP master, if you are not working
415 on the current master branch. Scripts are in `system/extras/simpleperf/scripts`, binaries are in
416 `system/extras/simpleperf/scripts/bin/android`.
417 3. It is recommended to use `app_profiler.py` for recording, and `report_html.py` for reporting.
418 Below is an example.
419
420 ```sh
421 # Record surfaceflinger process for 10 seconds with dwarf based call graph. More examples are in
422 # scripts reference in the doc.
423 $ python app_profiler.py -np surfaceflinger -r "-g --duration 10"
424
425 # Generate html report.
426 $ python report_html.py
427 ```
428
429 4. Since Android >= O has symbols for system libraries on device, we don't need to use unstripped
430 binaries in `$ANDROID_PRODUCT_OUT/symbols` to report call graphs. However, they are needed to add
431 source code and disassembly (with line numbers) in the report. Below is an example.
432
433 ```sh
434 # Doing recording with app_profiler.py or simpleperf on device, and generates perf.data on host.
435 $ python app_profiler.py -np surfaceflinger -r "--call-graph fp --duration 10"
436
437 # Collect unstripped binaries from $ANDROID_PRODUCT_OUT/symbols to binary_cache/.
438 $ python binary_cache_builder.py -lib $ANDROID_PRODUCT_OUT/symbols
439
440 # Report source code and disassembly. Disassembling all binaries is slow, so it's better to add
441 # --binary_filter option to only disassemble selected binaries.
442 $ python report_html.py --add_source_code --source_dirs $ANDROID_BUILD_TOP --add_disassembly \
443 --binary_filter surfaceflinger.so
444 ```
445
446
447 ## Executable commands reference
448
449 ### How simpleperf works
450
451 Modern CPUs have a hardware component called the performance monitoring unit (PMU). The PMU has
452 several hardware counters, counting events like how many cpu cycles have happened, how many
453 instructions have executed, or how many cache misses have happened.
454
455 The Linux kernel wraps these hardware counters into hardware perf events. In addition, the Linux
456 kernel also provides hardware independent software events and tracepoint events. The Linux kernel
457 exposes all events to userspace via the perf_event_open system call, which is used by simpleperf.
458
459 Simpleperf has three main commands: stat, record and report.
460
461 The stat command gives a summary of how many events have happened in the profiled processes in a
462 time period. Here’s how it works:
463 1. Given user options, simpleperf enables profiling by making a system call to the kernel.
464 2. The kernel enables counters while the profiled processes are running.
465 3. After profiling, simpleperf reads counters from the kernel, and reports a counter summary.
466
467 The record command records samples of the profiled processes in a time period. Here’s how it works:
468 1. Given user options, simpleperf enables profiling by making a system call to the kernel.
469 2. Simpleperf creates mapped buffers between simpleperf and the kernel.
470 3. The kernel enables counters while the profiled processes are running.
471 4. Each time a given number of events happen, the kernel dumps a sample to the mapped buffers.
472 5. Simpleperf reads samples from the mapped buffers and stores profiling data in a file called
473 perf.data.
474
475 The report command reads perf.data and any shared libraries used by the profiled processes,
476 and outputs a report showing where the time was spent.
477
478 ### Commands
479
480 Simpleperf supports several commands, listed below:
481
482 ```
483 The debug-unwind command: debug/test dwarf based offline unwinding, used for debugging simpleperf.
484 The dump command: dumps content in perf.data, used for debugging simpleperf.
485 The help command: prints help information for other commands.
486 The kmem command: collects kernel memory allocation information (will be replaced by Python scripts).
487 The list command: lists all event types supported on the Android device.
488 The record command: profiles processes and stores profiling data in perf.data.
489 The report command: reports profiling data in perf.data.
490 The report-sample command: reports each sample in perf.data, used for supporting integration of
491 simpleperf in Android Studio.
492 The stat command: profiles processes and prints counter summary.
493
494 ```
495
496 Each command supports different options, which can be seen through help message.
497
498 ```sh
499 # List all commands.
500 $ simpleperf --help
501
502 # Print help message for record command.
503 $ simpleperf record --help
504 ```
505
506 Below describes the most frequently used commands, which are list, stat, record and report.
507
508 ### The list command
509
510 The list command lists all events available on the device. Different devices may support different
511 events because they have different hardware and kernels.
512
513 ```sh
514 $ simpleperf list
515 List of hw-cache events:
516 branch-loads
517 ...
518 List of hardware events:
519 cpu-cycles
520 instructions
521 ...
522 List of software events:
523 cpu-clock
524 task-clock
525 ...
526 ```
527
528 On ARM/ARM64, the list command also shows a list of raw events, they are the events supported by
529 the ARM PMU on the device. The kernel has wrapped part of them into hardware events and hw-cache
530 events. For example, raw-cpu-cycles is wrapped into cpu-cycles, raw-instruction-retired is wrapped
531 into instructions. The raw events are provided in case we want to use some events supported on the
532 device, but unfortunately not wrapped by the kernel.
533
534 ### The stat command
535
536 The stat command is used to get event counter values of the profiled processes. By passing options,
537 we can select which events to use, which processes/threads to monitor, how long to monitor and the
538 print interval.
539
540 ```sh
541 # Stat using default events (cpu-cycles,instructions,...), and monitor process 7394 for 10 seconds.
542 $ simpleperf stat -p 7394 --duration 10
543 Performance counter statistics:
544
545 1,320,496,145 cpu-cycles # 0.131736 GHz (100%)
546 510,426,028 instructions # 2.587047 cycles per instruction (100%)
547 4,692,338 branch-misses # 468.118 K/sec (100%)
548 886.008130(ms) task-clock # 0.088390 cpus used (100%)
549 753 context-switches # 75.121 /sec (100%)
550 870 page-faults # 86.793 /sec (100%)
551
552 Total test time: 10.023829 seconds.
553 ```
554
555 #### Select events to stat
556
557 We can select which events to use via -e.
558
559 ```sh
560 # Stat event cpu-cycles.
561 $ simpleperf stat -e cpu-cycles -p 11904 --duration 10
562
563 # Stat event cache-references and cache-misses.
564 $ simpleperf stat -e cache-references,cache-misses -p 11904 --duration 10
565 ```
566
567 When running the stat command, if the number of hardware events is larger than the number of
568 hardware counters available in the PMU, the kernel shares hardware counters between events, so each
569 event is only monitored for part of the total time. In the example below, there is a percentage at
570 the end of each row, showing the percentage of the total time that each event was actually
571 monitored.
572
573 ```sh
574 # Stat using event cache-references, cache-references:u,....
575 $ simpleperf stat -p 7394 -e cache-references,cache-references:u,cache-references:k \
576 -e cache-misses,cache-misses:u,cache-misses:k,instructions --duration 1
577 Performance counter statistics:
578
579 4,331,018 cache-references # 4.861 M/sec (87%)
580 3,064,089 cache-references:u # 3.439 M/sec (87%)
581 1,364,959 cache-references:k # 1.532 M/sec (87%)
582 91,721 cache-misses # 102.918 K/sec (87%)
583 45,735 cache-misses:u # 51.327 K/sec (87%)
584 38,447 cache-misses:k # 43.131 K/sec (87%)
585 9,688,515 instructions # 10.561 M/sec (89%)
586
587 Total test time: 1.026802 seconds.
588 ```
589
590 In the example above, each event is monitored about 87% of the total time. But there is no
591 guarantee that any pair of events are always monitored at the same time. If we want to have some
592 events monitored at the same time, we can use --group.
593
594 ```sh
595 # Stat using event cache-references, cache-references:u,....
596 $ simpleperf stat -p 7964 --group cache-references,cache-misses \
597 --group cache-references:u,cache-misses:u --group cache-references:k,cache-misses:k \
598 -e instructions --duration 1
599 Performance counter statistics:
600
601 3,638,900 cache-references # 4.786 M/sec (74%)
602 65,171 cache-misses # 1.790953% miss rate (74%)
603 2,390,433 cache-references:u # 3.153 M/sec (74%)
604 32,280 cache-misses:u # 1.350383% miss rate (74%)
605 879,035 cache-references:k # 1.251 M/sec (68%)
606 30,303 cache-misses:k # 3.447303% miss rate (68%)
607 8,921,161 instructions # 10.070 M/sec (86%)
608
609 Total test time: 1.029843 seconds.
610 ```
611
612 #### Select target to stat
613
614 We can select which processes or threads to monitor via -p or -t. Monitoring a
615 process is the same as monitoring all threads in the process. Simpleperf can also fork a child
616 process to run the new command and then monitor the child process.
617
618 ```sh
619 # Stat process 11904 and 11905.
620 $ simpleperf stat -p 11904,11905 --duration 10
621
622 # Stat thread 11904 and 11905.
623 $ simpleperf stat -t 11904,11905 --duration 10
624
625 # Start a child process running `ls`, and stat it.
626 $ simpleperf stat ls
627
628 # Stat the process of an Android application. This only works for debuggable apps on non-rooted
629 # devices.
630 $ simpleperf stat --app com.example.simpleperf.simpleperfexamplewithnative
631
632 # Stat system wide using -a.
633 $ simpleperf stat -a --duration 10
634 ```
635
636 #### Decide how long to stat
637
638 When monitoring existing threads, we can use --duration to decide how long to monitor. When
639 monitoring a child process running a new command, simpleperf monitors until the child process ends.
640 In this case, we can use Ctrl-C to stop monitoring at any time.
641
642 ```sh
643 # Stat process 11904 for 10 seconds.
644 $ simpleperf stat -p 11904 --duration 10
645
646 # Stat until the child process running `ls` finishes.
647 $ simpleperf stat ls
648
649 # Stop monitoring using Ctrl-C.
650 $ simpleperf stat -p 11904 --duration 10
651 ^C
652 ```
653
654 If you want to write a script to control how long to monitor, you can send one of SIGINT, SIGTERM,
655 SIGHUP signals to simpleperf to stop monitoring.
656
657 #### Decide the print interval
658
659 When monitoring perf counters, we can also use --interval to decide the print interval.
660
661 ```sh
662 # Print stat for process 11904 every 300ms.
663 $ simpleperf stat -p 11904 --duration 10 --interval 300
664
665 # Print system wide stat at interval of 300ms for 10 seconds. Note that system wide profiling needs
666 # root privilege.
667 $ su 0 simpleperf stat -a --duration 10 --interval 300
668 ```
669
670 #### Display counters in systrace
671
672 Simpleperf can also work with systrace to dump counters in the collected trace. Below is an example
673 to do a system wide stat.
674
675 ```sh
676 # Capture instructions (kernel only) and cache misses with interval of 300 milliseconds for 15
677 # seconds.
678 $ su 0 simpleperf stat -e instructions:k,cache-misses -a --interval 300 --duration 15
679 # On host launch systrace to collect trace for 10 seconds.
680 (HOST)$ external/chromium-trace/systrace.py --time=10 -o new.html sched gfx view
681 # Open the collected new.html in browser and perf counters will be shown up.
682 ```
683
684 ### The record command
685
686 The record command is used to dump samples of the profiled processes. Each sample can contain
687 information like the time at which the sample was generated, the number of events since last
688 sample, the program counter of a thread, the call chain of a thread.
689
690 By passing options, we can select which events to use, which processes/threads to monitor,
691 what frequency to dump samples, how long to monitor, and where to store samples.
692
693 ```sh
694 # Record on process 7394 for 10 seconds, using default event (cpu-cycles), using default sample
695 # frequency (4000 samples per second), writing records to perf.data.
696 $ simpleperf record -p 7394 --duration 10
697 simpleperf I cmd_record.cpp:316] Samples recorded: 21430. Samples lost: 0.
698 ```
699
700 #### Select events to record
701
702 By default, the cpu-cycles event is used to evaluate consumed cpu cycles. But we can also use other
703 events via -e.
704
705 ```sh
706 # Record using event instructions.
707 $ simpleperf record -e instructions -p 11904 --duration 10
708
709 # Record using task-clock, which shows the passed CPU time in nanoseconds.
710 $ simpleperf record -e task-clock -p 11904 --duration 10
711 ```
712
713 #### Select target to record
714
715 The way to select target in record command is similar to that in the stat command.
716
717 ```sh
718 # Record process 11904 and 11905.
719 $ simpleperf record -p 11904,11905 --duration 10
720
721 # Record thread 11904 and 11905.
722 $ simpleperf record -t 11904,11905 --duration 10
723
724 # Record a child process running `ls`.
725 $ simpleperf record ls
726
727 # Record the process of an Android application. This only works for debuggable apps on non-rooted
728 # devices.
729 $ simpleperf record --app com.example.simpleperf.simpleperfexamplewithnative
730
731 # Record system wide.
732 $ simpleperf record -a --duration 10
733 ```
734
735 #### Set the frequency to record
736
737 We can set the frequency to dump records via -f or -c. For example, -f 4000 means
738 dumping approximately 4000 records every second when the monitored thread runs. If a monitored
739 thread runs 0.2s in one second (it can be preempted or blocked in other times), simpleperf dumps
740 about 4000 * 0.2 / 1.0 = 800 records every second. Another way is using -c. For example, -c 10000
741 means dumping one record whenever 10000 events happen.
742
743 ```sh
744 # Record with sample frequency 1000: sample 1000 times every second running.
745 $ simpleperf record -f 1000 -p 11904,11905 --duration 10
746
747 # Record with sample period 100000: sample 1 time every 100000 events.
748 $ simpleperf record -c 100000 -t 11904,11905 --duration 10
749 ```
750
751 To avoid taking too much time generating samples, kernel >= 3.10 sets the max percent of cpu time
752 used for generating samples (default is 25%), and decreases the max allowed sample frequency when
753 hitting that limit. Simpleperf uses --cpu-percent option to adjust it, but it needs either root
754 privilege or to be on Android >= Q.
755
756 ```sh
757 # Record with sample frequency 10000, with max allowed cpu percent to be 50%.
758 $ simpleperf record -f 1000 -p 11904,11905 --duration 10 --cpu-percent 50
759 ```
760
761 #### Decide how long to record
762
763 The way to decide how long to monitor in record command is similar to that in the stat command.
764
765 ```sh
766 # Record process 11904 for 10 seconds.
767 $ simpleperf record -p 11904 --duration 10
768
769 # Record until the child process running `ls` finishes.
770 $ simpleperf record ls
771
772 # Stop monitoring using Ctrl-C.
773 $ simpleperf record -p 11904 --duration 10
774 ^C
775 ```
776
777 If you want to write a script to control how long to monitor, you can send one of SIGINT, SIGTERM,
778 SIGHUP signals to simpleperf to stop monitoring.
779
780 #### Set the path to store profiling data
781
782 By default, simpleperf stores profiling data in perf.data in the current directory. But the path
783 can be changed using -o.
784
785 ```sh
786 # Write records to data/perf2.data.
787 $ simpleperf record -p 11904 -o data/perf2.data --duration 10
788 ```
789
790 <a name="record-call-graphs-in-record-cmd"></a>
791 #### Record call graphs
792
793 A call graph is a tree showing function call relations. Below is an example.
794
795 ```
796 main() {
797 FunctionOne();
798 FunctionTwo();
799 }
800 FunctionOne() {
801 FunctionTwo();
802 FunctionThree();
803 }
804 a call graph:
805 main-> FunctionOne
806 | |
807 | |-> FunctionTwo
808 | |-> FunctionThree
809 |
810 |-> FunctionTwo
811 ```
812
813 A call graph shows how a function calls other functions, and a reversed call graph shows how
814 a function is called by other functions. To show a call graph, we need to first record it, then
815 report it.
816
817 There are two ways to record a call graph, one is recording a dwarf based call graph, the other is
818 recording a stack frame based call graph. Recording dwarf based call graphs needs support of debug
819 information in native binaries. While recording stack frame based call graphs needs support of
820 stack frame registers.
821
822 ```sh
823 # Record a dwarf based call graph
824 $ simpleperf record -p 11904 -g --duration 10
825
826 # Record a stack frame based call graph
827 $ simpleperf record -p 11904 --call-graph fp --duration 10
828 ```
829
830 [Here](#suggestions-about-recording-call-graphs) are some suggestions about recording call graphs.
831
832 <a name="record-both-on-cpu-time-and-off-cpu-time-in-record-cmd"></a>
833 #### Record both on CPU time and off CPU time
834
835 Simpleperf is a CPU profiler, it generates samples for a thread only when it is running on a CPU.
836 However, sometimes we want to figure out where the time of a thread is spent, whether it is running
837 on a CPU, or staying in the kernel's ready queue, or waiting for something like I/O events.
838
839 To support this, the record command uses --trace-offcpu to trace both on CPU time and off CPU time.
840 When --trace-offcpu is used, simpleperf generates a sample when a running thread is scheduled out,
841 so we know the callstack of a thread when it is scheduled out. And when reporting a perf.data
842 generated with --trace-offcpu, we use time to the next sample (instead of event counts from the
843 previous sample) as the weight of the current sample. As a result, we can get a call graph based
844 on timestamps, including both on CPU time and off CPU time.
845
846 trace-offcpu is implemented using sched:sched_switch tracepoint event, which may not be supported
847 on old kernels. But it is guaranteed to be supported on devices >= Android O MR1. We can check
848 whether trace-offcpu is supported as below.
849
850 ```sh
851 $ simpleperf list --show-features
852 dwarf-based-call-graph
853 trace-offcpu
854 ```
855
856 If trace-offcpu is supported, it will be shown in the feature list. Then we can try it.
857
858 ```sh
859 # Record with --trace-offcpu.
860 $ simpleperf record -g -p 11904 --duration 10 --trace-offcpu
861
862 # Record with --trace-offcpu using app_profiler.py.
863 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative -a .SleepActivity \
864 -r "-g -e task-clock:u -f 1000 --duration 10 --trace-offcpu"
865 ```
866
867 Below is an example comparing the profiling result with / without --trace-offcpu.
868 First we record without --trace-offcpu.
869
870 ```sh
871 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative -a .SleepActivity
872
873 $ python report_html.py --add_disassembly --add_source_code --source_dirs ../demo
874 ```
875
876 The result is [here](./without_trace_offcpu.html).
877 In the result, all time is taken by RunFunction(), and sleep time is ignored.
878 But if we add --trace-offcpu, the result changes.
879
880 ```sh
881 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative -a .SleepActivity \
882 -r "-g -e task-clock:u --trace-offcpu -f 1000 --duration 10"
883
884 $ python report_html.py --add_disassembly --add_source_code --source_dirs ../demo
885 ```
886
887 The result is [here](./trace_offcpu.html).
888 In the result, half of the time is taken by RunFunction(), and the other half is taken by
889 SleepFunction(). So it traces both on CPU time and off CPU time.
890
891 ### The report command
892
893 The report command is used to report profiling data generated by the record command. The report
894 contains a table of sample entries. Each sample entry is a row in the report. The report command
895 groups samples belong to the same process, thread, library, function in the same sample entry. Then
896 sort the sample entries based on the event count a sample entry has.
897
898 By passing options, we can decide how to filter out uninteresting samples, how to group samples
899 into sample entries, and where to find profiling data and binaries.
900
901 Below is an example. Records are grouped into 4 sample entries, each entry is a row. There are
902 several columns, each column shows piece of information belonging to a sample entry. The first
903 column is Overhead, which shows the percentage of events inside the current sample entry in total
904 events. As the perf event is cpu-cycles, the overhead is the percentage of CPU cycles used in each
905 function.
906
907 ```sh
908 # Reports perf.data, using only records sampled in libsudo-game-jni.so, grouping records using
909 # thread name(comm), process id(pid), thread id(tid), function name(symbol), and showing sample
910 # count for each row.
911 $ simpleperf report --dsos /data/app/com.example.sudogame-2/lib/arm64/libsudo-game-jni.so \
912 --sort comm,pid,tid,symbol -n
913 Cmdline: /data/data/com.example.sudogame/simpleperf record -p 7394 --duration 10
914 Arch: arm64
915 Event: cpu-cycles (type 0, config 0)
916 Samples: 28235
917 Event count: 546356211
918
919 Overhead Sample Command Pid Tid Symbol
920 59.25% 16680 sudogame 7394 7394 checkValid(Board const&, int, int)
921 20.42% 5620 sudogame 7394 7394 canFindSolution_r(Board&, int, int)
922 13.82% 4088 sudogame 7394 7394 randomBlock_r(Board&, int, int, int, int, int)
923 6.24% 1756 sudogame 7394 7394 @plt
924 ```
925
926 #### Set the path to read profiling data
927
928 By default, the report command reads profiling data from perf.data in the current directory.
929 But the path can be changed using -i.
930
931 ```sh
932 $ simpleperf report -i data/perf2.data
933 ```
934
935 #### Set the path to find binaries
936
937 To report function symbols, simpleperf needs to read executable binaries used by the monitored
938 processes to get symbol table and debug information. By default, the paths are the executable
939 binaries used by monitored processes while recording. However, these binaries may not exist when
940 reporting or not contain symbol table and debug information. So we can use --symfs to redirect
941 the paths.
942
943 ```sh
944 # In this case, when simpleperf wants to read executable binary /A/b, it reads file in /A/b.
945 $ simpleperf report
946
947 # In this case, when simpleperf wants to read executable binary /A/b, it prefers file in
948 # /debug_dir/A/b to file in /A/b.
949 $ simpleperf report --symfs /debug_dir
950
951 # Read symbols for system libraries built locally. Note that this is not needed since Android O,
952 # which ships symbols for system libraries on device.
953 $ simpleperf report --symfs $ANDROID_PRODUCT_OUT/symbols
954 ```
955
956 #### Filter samples
957
958 When reporting, it happens that not all records are of interest. The report command supports four
959 filters to select samples of interest.
960
961 ```sh
962 # Report records in threads having name sudogame.
963 $ simpleperf report --comms sudogame
964
965 # Report records in process 7394 or 7395
966 $ simpleperf report --pids 7394,7395
967
968 # Report records in thread 7394 or 7395.
969 $ simpleperf report --tids 7394,7395
970
971 # Report records in libsudo-game-jni.so.
972 $ simpleperf report --dsos /data/app/com.example.sudogame-2/lib/arm64/libsudo-game-jni.so
973 ```
974
975 #### Group samples into sample entries
976
977 The report command uses --sort to decide how to group sample entries.
978
979 ```sh
980 # Group records based on their process id: records having the same process id are in the same
981 # sample entry.
982 $ simpleperf report --sort pid
983
984 # Group records based on their thread id and thread comm: records having the same thread id and
985 # thread name are in the same sample entry.
986 $ simpleperf report --sort tid,comm
987
988 # Group records based on their binary and function: records in the same binary and function are in
989 # the same sample entry.
990 $ simpleperf report --sort dso,symbol
991
992 # Default option: --sort comm,pid,tid,dso,symbol. Group records in the same thread, and belong to
993 # the same function in the same binary.
994 $ simpleperf report
995 ```
996
997 <a name="report-call-graphs-in-report-cmd"></a>
998 #### Report call graphs
999
1000 To report a call graph, please make sure the profiling data is recorded with call graphs,
1001 as [here](#record-call-graphs-in-record-cmd).
1002
1003 ```
1004 $ simpleperf report -g
1005 ```
1006
1007 ## Scripts reference
1008
1009 <a name="app_profiler-py"></a>
1010 ### app_profiler.py
1011
1012 app_profiler.py is used to record profiling data for Android applications and native executables.
1013
1014 ```sh
1015 # Record an Android application.
1016 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative
1017
1018 # Record an Android application with Java code compiled into native instructions.
1019 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative --compile_java_code
1020
1021 # Record the launch of an Activity of an Android application.
1022 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative -a .SleepActivity
1023
1024 # Record a native process.
1025 $ python app_profiler.py -np surfaceflinger
1026
1027 # Record a native process given its pid.
1028 $ python app_profiler.py --pid 11324
1029
1030 # Record a command.
1031 $ python app_profiler.py -cmd \
1032 "dex2oat --dex-file=/data/local/tmp/app-profiling.apk --oat-file=/data/local/tmp/a.oat"
1033
1034 # Record an Android application, and use -r to send custom options to the record command.
1035 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative \
1036 -r "-e cpu-clock -g --duration 30"
1037
1038 # Record both on CPU time and off CPU time.
1039 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative \
1040 -r "-e task-clock -g -f 1000 --duration 10 --trace-offcpu"
1041
1042 # Save profiling data in a custom file (like perf_custom.data) instead of perf.data.
1043 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative -o perf_custom.data
1044 ```
1045
1046 #### Profile from launch of an application
1047
1048 Sometimes we want to profile the launch-time of an application. To support this, we added --app in
1049 the record command. The --app option sets the package name of the Android application to profile.
1050 If the app is not already running, the record command will poll for the app process in a loop with
1051 an interval of 1ms. So to profile from launch of an application, we can first start the record
1052 command with --app, then start the app. Below is an example.
1053
1054 ```sh
1055 $ python run_simpleperf_on_device.py record
1056 --app com.example.simpleperf.simpleperfexamplewithnative \
1057 -g --duration 1 -o /data/local/tmp/perf.data
1058 # Start the app manually or using the `am` command.
1059 ```
1060
1061 To make it convenient to use, app_profiler.py supports using the -a option to start an Activity
1062 after recording has started.
1063
1064 ```sh
1065 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative -a .MainActivity
1066 ```
1067
1068 <a name="run_simpleperf_without_usb_connection-py"></a>
1069 ### run_simpleperf_without_usb_connection.py
1070
1071 run_simpleperf_without_usb_connection.py records profiling data while the USB cable isn't
1072 connected. Below is an example.
1073
1074 ```sh
1075 $ python run_simpleperf_without_usb_connection.py start \
1076 -p com.example.simpleperf.simpleperfexamplewithnative
1077 # After the command finishes successfully, unplug the USB cable, run the
1078 # SimpleperfExampleWithNative app. After a few seconds, plug in the USB cable.
1079 $ python run_simpleperf_without_usb_connection.py stop
1080 # It may take a while to stop recording. After that, the profiling data is collected in perf.data
1081 # on host.
1082 ```
1083
1084 <a name="binary_cache_builder-py"></a>
1085 ### binary_cache_builder.py
1086
1087 The binary_cache directory is a directory holding binaries needed by a profiling data file. The
1088 binaries are expected to be unstripped, having debug information and symbol tables. The
1089 binary_cache directory is used by report scripts to read symbols of binaries. It is also used by
1090 report_html.py to generate annotated source code and disassembly.
1091
1092 By default, app_profiler.py builds the binary_cache directory after recording. But we can also
1093 build binary_cache for existing profiling data files using binary_cache_builder.py. It is useful
1094 when you record profiling data using `simpleperf record` directly, to do system wide profiling or
1095 record without the USB cable connected.
1096
1097 binary_cache_builder.py can either pull binaries from an Android device, or find binaries in
1098 directories on the host (via -lib).
1099
1100 ```sh
1101 # Generate binary_cache for perf.data, by pulling binaries from the device.
1102 $ python binary_cache_builder.py
1103
1104 # Generate binary_cache, by pulling binaries from the device and finding binaries in
1105 # SimpleperfExampleWithNative.
1106 $ python binary_cache_builder.py -lib path_of_SimpleperfExampleWithNative
1107 ```
1108
1109 <a name="run_simpleperf_on_device-py"></a>
1110 ### run_simpleperf_on_device.py
1111
1112 This script pushes the simpleperf executable on the device, and run a simpleperf command on the
1113 device. It is more convenient than running adb commands manually.
1114
1115 <a name="report-py"></a>
1116 ### report.py
1117
1118 report.py is a wrapper of the report command on the host. It accepts all options of the report
1119 command.
1120
1121 ```sh
1122 # Report call graph
1123 $ python report.py -g
1124
1125 # Report call graph in a GUI window implemented by Python Tk.
1126 $ python report.py -g --gui
1127 ```
1128
1129 <a name="report_html-py"></a>
1130 ### report_html.py
1131
1132 report_html.py generates report.html based on the profiling data. Then the report.html can show
1133 the profiling result without depending on other files. So it can be shown in local browsers or
1134 passed to other machines. Depending on which command-line options are used, the content of the
1135 report.html can include: chart statistics, sample table, flame graphs, annotated source code for
1136 each function, annotated disassembly for each function.
1137
1138 ```sh
1139 # Generate chart statistics, sample table and flame graphs, based on perf.data.
1140 $ python report_html.py
1141
1142 # Add source code.
1143 $ python report_html.py --add_source_code --source_dirs path_of_SimpleperfExampleWithNative
1144
1145 # Add disassembly.
1146 $ python report_html.py --add_disassembly
1147
1148 # Adding disassembly for all binaries can cost a lot of time. So we can choose to only add
1149 # disassembly for selected binaries.
1150 $ python report_html.py --add_disassembly --binary_filter libgame.so
1151
1152 # report_html.py accepts more than one recording data file.
1153 $ python report_html.py -i perf1.data perf2.data
1154 ```
1155
1156 Below is an example of generating html profiling results for SimpleperfExampleWithNative.
1157
1158 ```sh
1159 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative
1160 $ python report_html.py --add_source_code --source_dirs path_of_SimpleperfExampleWithNative \
1161 --add_disassembly
1162 ```
1163
1164 After opening the generated [report.html](./report_html.html) in a browser, there are several tabs:
1165
1166 The first tab is "Chart Statistics". You can click the pie chart to show the time consumed by each
1167 process, thread, library and function.
1168
1169 The second tab is "Sample Table". It shows the time taken by each function. By clicking one row in
1170 the table, we can jump to a new tab called "Function".
1171
1172 The third tab is "Flamegraph". It shows the flame graphs generated by [inferno](./inferno.md).
1173
1174 The fourth tab is "Function". It only appears when users click a row in the "Sample Table" tab.
1175 It shows information of a function, including:
1176
1177 1. A flame graph showing functions called by that function.
1178 2. A flame graph showing functions calling that function.
1179 3. Annotated source code of that function. It only appears when there are source code files for
1180 that function.
1181 4. Annotated disassembly of that function. It only appears when there are binaries containing that
1182 function.
1183
1184 ### inferno
1185
1186 [inferno](./inferno.md) is a tool used to generate flame graph in a html file.
1187
1188 ```sh
1189 # Generate flame graph based on perf.data.
1190 # On Windows, use inferno.bat instead of ./inferno.sh.
1191 $ ./inferno.sh -sc --record_file perf.data
1192
1193 # Record a native program and generate flame graph.
1194 $ ./inferno.sh -np surfaceflinger
1195 ```
1196
1197 <a name="pprof_proto_generator-py"></a>
1198 ### pprof_proto_generator.py
1199
1200 It converts a profiling data file into pprof.proto, a format used by [pprof](https://github.com/google/pprof).
1201
1202 ```sh
1203 # Convert perf.data in the current directory to pprof.proto format.
1204 $ python pprof_proto_generator.py
1205 $ pprof -pdf pprof.profile
1206 ```
1207
1208 <a name="report_sample-py"></a>
1209 ### report_sample.py
1210
1211 It converts a profiling data file into a format used by [FlameGraph](https://github.com/brendangregg/FlameGraph).
1212
1213 ```sh
1214 # Convert perf.data in the current directory to a format used by FlameGraph.
1215 $ python report_sample.py --symfs binary_cache >out.perf
1216 $ git clone https://github.com/brendangregg/FlameGraph.git
1217 $ FlameGraph/stackcollapse-perf.pl out.perf >out.folded
1218 $ FlameGraph/flamegraph.pl out.folded >a.svg
1219 ```
1220
1221 <a name="simpleperf_report_lib-py"></a>
1222 ### simpleperf_report_lib.py
1223
1224 simpleperf_report_lib.py is a Python library used to parse profiling data files generated by the
1225 record command. Internally, it uses libsimpleperf_report.so to do the work. Generally, for each
1226 profiling data file, we create an instance of ReportLib, pass it the file path (via SetRecordFile).
1227 Then we can read all samples through GetNextSample(). For each sample, we can read its event info
1228 (via GetEventOfCurrentSample), symbol info (via GetSymbolOfCurrentSample) and call chain info
1229 (via GetCallChainOfCurrentSample). We can also get some global information, like record options
1230 (via GetRecordCmd), the arch of the device (via GetArch) and meta strings (via MetaInfo).
1231
1232 Examples of using simpleperf_report_lib.py are in report_sample.py, report_html.py,
1233 pprof_proto_generator.py and inferno/inferno.py.
1234
1235 ## Answers to common issues
1236
1237 ### Why we suggest profiling on Android >= N devices?
1238 ```
1239 1. Running on a device reflects a real running situation, so we suggest
1240 profiling on real devices instead of emulators.
1241 2. To profile Java code, we need ART running in oat mode, which is only
1242 available >= L for rooted devices, and >= N for non-rooted devices.
1243 3. Old Android versions are likely to be shipped with old kernels (< 3.18),
1244 which may not support profiling features like recording dwarf based call graphs.
1245 4. Old Android versions are likely to be shipped with Arm32 chips. In Arm32
1246 mode, recording stack frame based call graphs doesn't work well.
1247 ```
1248
1249 ### Suggestions about recording call graphs
1250
1251 Below is our experiences of dwarf based call graphs and stack frame based call graphs.
1252
1253 dwarf based call graphs:
1254 1. Need support of debug information in binaries.
1255 2. Behave normally well on both ARM and ARM64, for both fully compiled Java code and C++ code.
1256 3. Can only unwind 64K stack for each sample. So usually can't show complete flame-graph. But
1257 probably is enough for users to identify hot places.
1258 4. Take more CPU time than stack frame based call graphs. So the sample frequency is suggested
1259 to be 1000 Hz. Thus at most 1000 samples per second.
1260
1261 stack frame based call graphs:
1262 1. Need support of stack frame registers.
1263 2. Don't work well on ARM. Because ARM is short of registers, and ARM and THUMB code have different
1264 stack frame registers. So the kernel can't unwind user stack containing both ARM/THUMB code.
1265 3. Also don't work well on fully compiled Java code on ARM64. Because the ART compiler doesn't
1266 reserve stack frame registers.
1267 4. Work well when profiling native programs on ARM64. One example is profiling surfacelinger. And
1268 usually shows complete flame-graph when it works well.
1269 5. Take less CPU time than dwarf based call graphs. So the sample frequency can be 4000 Hz or
1270 higher.
1271
1272 So if you need to profile code on ARM or profile fully compiled Java code, dwarf based call graphs
1273 may be better. If you need to profile C++ code on ARM64, stack frame based call graphs may be
1274 better. After all, you can always try dwarf based call graph first, because it always produces
1275 reasonable results when given unstripped binaries properly. If it doesn't work well enough, then
1276 try stack frame based call graphs instead.
1277
1278 Simpleperf needs to have unstripped native binaries on the device to generate good dwarf based call
1279 graphs. It can be supported in two ways:
1280 1. Use unstripped native binaries when building the apk, as [here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/demo/SimpleperfExampleWithNative/app/profiling.gradle).
1281 2. Pass directory containing unstripped native libraries to app_profiler.py via -lib. And it will
1282 download the unstripped native libraries on the device.
1283
1284 ```sh
1285 $ python app_profiler.py -lib NATIVE_LIB_DIR
1286 ```
1287
1288 ### How to solve missing symbols in report?
1289
1290 The simpleperf record command collects symbols on device in perf.data. But if the native libraries
1291 you use on device are stripped, this will result in a lot of unknown symbols in the report. A
1292 solution is to build binary_cache on host.
1293
1294 ```sh
1295 # Collect binaries needed by perf.data in binary_cache/.
1296 $ python binary_cache_builder.py -lib NATIVE_LIB_DIR,...
1297 ```
1298
1299 The NATIVE_LIB_DIRs passed in -lib option are the directories containing unstripped native
1300 libraries on host. After running it, the native libraries containing symbol tables are collected
1301 in binary_cache/ for use when reporting.
1302
1303 ```sh
1304 $ python report.py --symfs binary_cache
1305
1306 # report_html.py searches binary_cache/ automatically, so you don't need to
1307 # pass it any argument.
1308 $ python report_html.py
1309 ```
1310
1311 ## Bugs and contribution
1312
1313 Bugs and feature requests can be submitted at http://github.com/android-ndk/ndk/issues.
1314 Patches can be uploaded to android-review.googlesource.com as [here](https://source.android.com/setup/contribute/),
1315 or sent to email addresses listed [here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/OWNERS).
1316
1317 If you want to compile simpleperf C++ source code, follow below steps:
1318 1. Download AOSP master branch as [here](https://source.android.com/setup/build/requirements).
1319 2. Build simpleperf.
1320 ```sh
1321 $ . build/envsetup.sh
1322 $ lunch aosp_arm64-userdebug
1323 $ mmma system/extras/simpleperf -j30
1324 ```
1325
1326 If built successfully, out/target/product/generic_arm64/system/bin/simpleperf is for ARM64, and
1327 out/target/product/generic_arm64/system/bin/simpleperf32 is for ARM.