|
|
@@ -0,0 +1,98 @@
|
|
|
+# 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
|
|
|
+ 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
|
|
|
+
|
Alexander Færøy