git.cworth.org Git - apitrace/blob - Dalvik.markdown

   1 Tracing Dalvik VM (Java) applications on Android
   2 ================================================
   3
   4 Android's Java virtual machine, Dalvik, runs as a system service (started at
   5 bootup by `init`) and Java applications are run by forks of the initial
   6 resident process.  Thus, injecting apitrace's tracing library is different from
   7 other operating systems.
   8
   9 The following discussion assumes that tracing library is copied to '/data':
  10
  11     adb push /path/to/apitrace/build/wrappers/egltrace.so /data
  12
  13 Tracing on Android 4.0 and newer
  14 --------------------------------
  15
  16 Starting from Android 4.0 (Ice Cream Sandwich) release, Dalvik supports
  17 running designated processes with wrappers, in which case a new Java VM is
  18 started with 'system()' library call for that process.
  19
  20 Obtain the process name of the application to be traced (the one reported in
  21 `ps` output, such as `com.android.settings`), and set two system properties:
  22
  23     PROCNAME=com.android.settings
  24     adb shell setprop wrap.$PROCNAME LD_PRELOAD=/data/egltrace.so
  25     adb shell setprop debug.apitrace.procname $PROCNAME
  26
  27 (the former is read by Dalvik and specifies wrapping prefix, the latter is
  28 read by apitrace itself and used in case apitrace is preloaded into Java VM
  29 globally to specify which process should be traced).
  30
  31 Make sure the process is not loaded before starting to trace it, for example
  32 use `-S` flag to `am start`:
  33
  34     adb shell am start -S $PROCNAME
  35
  36 Use `adb logcat \*:S apitrace` to examine apitrace debug output.  Trace files
  37 are saved into '/data/' directory by default:
  38
  39     adb pull /data/$PROCNAME.trace
  40     adb shell rm /data/$PROCNAME.trace
  41
  42 (you need to `chmod 0777 /data` beforehand).
  43
  44
  45 Injecting tracing library globally
  46 ----------------------------------
  47
  48 If `LD_PRELOAD` is supported (Android 2.3 "Gingerbread" and newer), it is
  49 possible to inject `egltrace.so` into the resident Java VM, in which case
  50 `debug.apitrace.procname` system propery is used to control for which process
  51 tracing will be active.
  52
  53 Restarting 'zygote' (Java VM) service is not straightforward, since '/init.rc'
  54 is read only once at system bootup, and restored from the recovery image on
  55 reboots.   Thus, you either need to augment '/init.rc' in the recovery image
  56 with `setenv LD_PRELOAD /data/egltrace.so` in `service zygote` section, or you
  57 can use a tool such as
  58 [adjust-child-env](https://github.com/amonakov/adjust-child-env) to restart
  59 the service with modified environment.
  60
  61 Put `adjust-child-env` and a script with the following contents into `/data`:
  62
  63     stop zygote
  64     /data/adjust-child-env 1 /system/bin/app_process LD_PRELOAD=/data/egltrace.so &
  65     sleep 1
  66     start zygote
  67
  68 The scripts restarts the Java VM ('zygote') with modified environment.
  69
  70 Invoke the script with `adb shell` to prepare for tracing, and then follow the
  71 Android 4.0 directions.