doc/HACKING/android/Simpleperf.md

   1 # Using `simpleperf` to collect CPU profiling on Android
   2
   3 This document describes how you can use Android's `simpleperf`
   4 command-line tool to get CPU profiling information from Tor via the
   5 Orbot application. The tool is particularly useful for Tor development
   6 because it is able to profile native applications on the platform
   7 whereas a lot of the normal tooling for the Android platform is only
   8 able to collect information from Java-based applications.
   9
  10 ## Prerequisites
  11
  12 Before using `simpleperf` there is a couple of steps that must be
  13 followed. You should make sure you have both a recent installation of
  14 the Android Software Development Kit (SDK) and Native Development Kit
  15 (NDK) installed. These can be found on the Android Developers website.
  16
  17 1. Follow the build instructions from the `BUILD` file in the Orbot
  18    repository and build an Orbot APK (Android Package) file with
  19    debugging enabled. Make sure that when you build the native content of
  20    the Orbot application that you run the `make -C external` command with
  21    an additional `DEBUG=1` as parameter to ensure that the Orbot build
  22    process does not strip the debug symbols from the Tor binary.
  23
  24 2. (Optional) Uninstall and clean-up your old Orbot installation that
  25    is most likely downloaded from Google's Play Store or via fdroid:
  26
  27        $ adb shell pm clear org.torproject.android
  28        $ adb uninstall org.torproject.android
  29
  30 3. Install the Android Package you generated in step 1:
  31
  32 ```bash
  33        $ adb install /path/to/your/app-fullperm-debug.apk
  34 ```
  35
  36 4. Check on your device that the newly installed Orbot actually works
  37    and behaves in the way you expect it to.
  38
  39 ## Profiling using `simpleperf`
  40
  41 The `simpleperf` tool can be found in the `simpleperf/` directory in
  42 the directory where you installed the Android NDK to. In this
  43 directory there is a set of Python files that will help you deploy the
  44 tool to a device and collect the measurement data such that you can
  45 analyze the results on your computer rather than on your phone.
  46
  47 1. Change directory to the location of the `simpleperf` directory.
  48 2. Open the `app_profiler.config` file and change
  49    `app_package_name` to `org.torproject.android`, `apk_file_path` to
  50    the path of your Orbot Android Package (APK file).
  51 3. Optionally change the duration parameter in the `record_options`
  52    variable in `app_profiler.config` to the duration which you would like
  53    to collect samples in. The value is specified in seconds.
  54 4. Run the app profiler using `python app_profiler.py`. This helper
  55    script will push the `simpleperf` tool to your device, start the
  56    profiler, and once it has completed copy the generated `perf.data`
  57    file over to your computer with the results.
  58
  59 ### Analyzing the results
  60
  61 You can inspect your resulting `perf.data` file via a simple GUI
  62 program `python report.py` or via the command-line tool `simpleperf
  63 report`. I've found the GUI tool to be easier to navigate around with
  64 than the command-line tool.
  65
  66 The `-g` option can be passed to the command line `simpleperf report`
  67 tool allows you to see the call graph of functions and how much time
  68 was spend on the call.
  69
  70 ## Tips & Tricks
  71
  72 - When you have installed Orbot the first time, you will notice that
  73   if you get a shell on the Android device that there is no Tor binary
  74   available. This is because Orbot unpacks the Tor binary first time it
  75   is executed and places it under the `app_bin/` directory on the
  76   device.
  77
  78   To access binaries, `torrc` files, and other useful information on
  79   the device do the following:
  80
  81 ```console
  82       $ adb shell
  83       (device):/ $ run-as org.torproject.android
  84       (device):/data/data/org.torproject.android $ ls
  85       app_bin app_data cache databases files lib shared_prefs
  86 ```
  87
  88   Descriptors, control authentication cookie, state, and other files can be
  89   found in the `app_data` directory. The `torrc` can be found in the `app_bin/`
  90   directory.
  91
  92 - You can enable logging in Tor via the syslog (or android) log
  93   mechanism with:
  94
  95 ```console
  96       $ adb shell
  97       (device):/ $ run-as org.torproject.android
  98       (device):/data/data/org.torproject.android $ echo -e "\nLog info syslog" >> app_bin/torrc
  99 ```
 100
 101   Start Tor the normal way via Orbot and collect the logs from your computer using
 102
 103 ```console
 104       $ adb logcat
 105 ```