Unverified Commit 251983eb authored by Alexander Færøy's avatar Alexander Færøy
Browse files

Add initial instructions on using Simpleperf for Android CPU profiling.

See: https://bugs.torproject.org/24062
parent 04812e59
Pipeline #14158696 passed with stage
in 9 minutes and 26 seconds
# Using `simpleperf` to collect CPU profiling on Android
This document describes how you can use Android's `simpleperf`
command-line tool to get CPU profiling information from Tor via the
Orbot application. The tool is particularly useful for Tor development
because it is able to profile native applications on the platform
whereas a lot of the normal tooling for the Android platform is only
able to collect information from Java-based applications.
## Prerequisites
Before using `simpleperf` there is a couple of steps that must be
followed. You should make sure you have both a recent installation of
the Android Software Development Kit (SDK) and Native Development Kit
(NDK) installed. These can be found on the Android Developers website.
1. Follow the build instructions from the `BUILD` file in the Orbot
repository and build an Orbot APK (Android Package) file with
debugging enabled. Make sure that when you build the native content of
the Orbot application that you run the `make -C external` command with
an additional `DEBUG=1` as paramter to ensure that the Orbot build
process does not strip the debug symbols from the Tor binary.
2. (Optional) Uninstall and clean-up your old Orbot installation that
is most likely downloaded from Google's Play Store or via fdroid:
$ adb shell pm clear org.torproject.android
$ adb uninstall org.torproject.android
3. Install the Android Package you generated in step 1:
$ adb install /path/to/your/app-fullperm-debug.apk
4. Check on your device that the newly installed Orbot actually works
and behaves in the way you expect it to.
## Profiling using `simpleperf`
The `simpleperf` tool can be found in the `simpleperf/` directory in
the directory where you installed the Android NDK to. In this
directory there is a set of Python files that will help you deploy the
tool to a device and collect the measurement data such that you can
analyze the results on your computer rather than on your phone.
1. Change directory to the location of the `simpleperf` directory.
2. Open the `app_profiler.config` file and change
`app_package_name` to `org.torproject.android`, `apk_file_path` to
the path of your Orbot Android Package (APK file).
3. Optionally change the duration parameter in the `record_options`
variable in `app_profiler.config` to the duration which you would like
to collect samples in. The value is specified in seconds.
4. Run the app profiler using `python app_profiler.py`. This helper
script will push the `simpleperf` tool to your device, start the
profiler, and once it has completed copy the generated `perf.data`
file over to your computer with the results.
### Analyzing the results
You can inspect your resulting `perf.data` file via a simple GUI
program `python report.py` or via the command-line tool `simpleperf
report`. I've found the GUI tool to be easier to navigate around with
than the command-line tool.
The `-g` option can be passed to the command line `simpleperf report`
tool allows you to see the call graph of functions and how much time
was spend on the call.
## Tips & Tricks
- When you have installed Orbot the first time, you will notice that
if you get a shell on the Android device that there is no Tor binary
available. This is because Orbot unpacks the Tor binary first time it
is executed and places it under the `app_bin/` directory on the
To access binaries, `torrc` files, and other useful information on
the device do the following:
$ adb shell
(device):/ $ run-as org.torproject.android
(device):/data/data/org.torproject.android $ ls
app_bin app_data cache databases files lib shared_prefs
Descriptors, control authentication cookie, state, and other files can be
found in the `app_data` directory. The `torrc` can be found in the `app_bin/`
- You can enable logging in Tor via the syslog (or android) log
mechanism with:
$ adb shell
(device):/ $ run-as org.torproject.android
(device):/data/data/org.torproject.android $ echo -e "\nLog info syslog" >> app_bin/torrc
Start Tor the normal way via Orbot and collect the logs from your computer using
$ adb logcat
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment