tor/doc/HACKING/android/Simpleperf.md

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