mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-12-11 21:23:35 +01:00
98 lines
4.1 KiB
Markdown
98 lines
4.1 KiB
Markdown
# 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 parameter 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
|
|
device.
|
|
|
|
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/`
|
|
directory.
|
|
|
|
- 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
|