Merge remote-tracking branch 'ahf-gitlab/ahf/24062-simpleperf'

doc/HACKING/android/Simpleperf.md

@@ -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
+