1*795d594fSAndroid Build Coastguard Worker# Titrace 2*795d594fSAndroid Build Coastguard Worker 3*795d594fSAndroid Build Coastguard WorkerTitrace is a bytecode instruction tracing tool that uses JVMTI and works on both ART and the RI. 4*795d594fSAndroid Build Coastguard Worker 5*795d594fSAndroid Build Coastguard Worker# Usage 6*795d594fSAndroid Build Coastguard Worker### Build 7*795d594fSAndroid Build Coastguard Worker> `m libtitrace` # or 'm libtitraced' with debugging checks enabled 8*795d594fSAndroid Build Coastguard Worker 9*795d594fSAndroid Build Coastguard WorkerThe libraries will be built for 32-bit, 64-bit, host and target. Below examples assume you want to use the 64-bit version. 10*795d594fSAndroid Build Coastguard Worker### Command Line 11*795d594fSAndroid Build Coastguard Worker#### ART 12*795d594fSAndroid Build Coastguard Worker> `art -Xplugin:$ANDROID_HOST_OUT/lib64/libopenjdkjvmti.so -agentpath:$ANDROID_HOST_OUT/lib64/libtitrace.so -cp tmp/java/helloworld.dex -Xint helloworld` 13*795d594fSAndroid Build Coastguard Worker 14*795d594fSAndroid Build Coastguard Worker* `-Xplugin` and `-agentpath` need to be used, otherwise libtitrace agent will fail during init. 15*795d594fSAndroid Build Coastguard Worker* If using `libartd.so`, make sure to use the debug version of jvmti. 16*795d594fSAndroid Build Coastguard Worker#### Reference Implementation 17*795d594fSAndroid Build Coastguard Worker> `java -agentpath:$ANDROID_HOST_OUT/lib64/libtitrace.so helloworld` 18*795d594fSAndroid Build Coastguard Worker 19*795d594fSAndroid Build Coastguard WorkerOnly needs `-agentpath` to be specified. 20*795d594fSAndroid Build Coastguard Worker### Android Applications 21*795d594fSAndroid Build Coastguard WorkerReplace __com.littleinc.orm_benchmark__ with the name of your application below. 22*795d594fSAndroid Build Coastguard Worker#### Enable permissions for attaching an agent 23*795d594fSAndroid Build Coastguard WorkerNormal applications require that `debuggable=true` to be set in their AndroidManifest.xml. 24*795d594fSAndroid Build Coastguard Worker 25*795d594fSAndroid Build Coastguard WorkerBy using a *eng* or *userdebug* build of Android, we can override this requirement: 26*795d594fSAndroid Build Coastguard Worker> `adb root` 27*795d594fSAndroid Build Coastguard Worker> `adb shell setprop dalvik.vm.dex2oat-flags --debuggable` 28*795d594fSAndroid Build Coastguard Worker 29*795d594fSAndroid Build Coastguard WorkerThen restart the runtime to pick it up. 30*795d594fSAndroid Build Coastguard Worker> `adb shell stop && adb shell start` 31*795d594fSAndroid Build Coastguard Worker 32*795d594fSAndroid Build Coastguard WorkerIf this step is skipped, attaching the agent will not succeed. 33*795d594fSAndroid Build Coastguard Worker#### Deploy agent to device 34*795d594fSAndroid Build Coastguard WorkerThe agent must be located in an app-accessible directory. 35*795d594fSAndroid Build Coastguard Worker 36*795d594fSAndroid Build Coastguard Worker> `adb push $ANDROID_PRODUCT_OUT/system/lib64/libtitrace.so /data/local/tmp` 37*795d594fSAndroid Build Coastguard Worker 38*795d594fSAndroid Build Coastguard WorkerUpload to device first (it gets shell/root permissions). 39*795d594fSAndroid Build Coastguard Worker 40*795d594fSAndroid Build Coastguard Worker> `adb shell run-as com.littleinc.orm_benchmark 'cp /data/local/tmp/libtitrace.so /data/data/com.littleinc.orm_benchmark/files/libtitrace.so'` 41*795d594fSAndroid Build Coastguard Worker 42*795d594fSAndroid Build Coastguard WorkerCopy the agent into an app-accessible directory, and make the file owned by the app. 43*795d594fSAndroid Build Coastguard Worker 44*795d594fSAndroid Build Coastguard Worker#### Attach agent to application 45*795d594fSAndroid Build Coastguard Worker 46*795d594fSAndroid Build Coastguard Worker##### Option 1: Attach the agent before any app code runs. 47*795d594fSAndroid Build Coastguard Worker> `adb shell am start --attach-agent /data/data/com.littleinc.orm_benchmark/files/libtitrace.so com.littleinc.orm_benchmark/.MainActivity` 48*795d594fSAndroid Build Coastguard Worker 49*795d594fSAndroid Build Coastguard WorkerNote: To determine the arguments to `am start`, launch the application manually first and then look for this in logcat: 50*795d594fSAndroid Build Coastguard Worker 51*795d594fSAndroid Build Coastguard Worker> 09-14 13:28:08.680 7584 8192 I ActivityManager: Start proc 17614:com.littleinc.orm_benchmark/u0a138 for activity **com.littleinc.orm_benchmark/.MainActivity** 52*795d594fSAndroid Build Coastguard Worker 53*795d594fSAndroid Build Coastguard Worker##### Option 2: Attach the agent to an already-running app. 54*795d594fSAndroid Build Coastguard Worker> `adb shell am attach-agent $(pid com.littleinc.orm_benchmark) /data/data/com.littleinc.orm_benchmark/files/libtitrace.so` 55*795d594fSAndroid Build Coastguard Worker 56*795d594fSAndroid Build Coastguard Worker### Printing the Results 57*795d594fSAndroid Build Coastguard WorkerAll statitics gathered during the trace are printed automatically when the program normally exists. In the case of Android applications, they are always killed, so we need to manually print the results. 58*795d594fSAndroid Build Coastguard Worker 59*795d594fSAndroid Build Coastguard Worker> `kill -SIGQUIT $(pid com.littleinc.orm_benchmark)` 60*795d594fSAndroid Build Coastguard Worker 61*795d594fSAndroid Build Coastguard WorkerWill initiate a dump of the agent (to logcat). 62*795d594fSAndroid Build Coastguard Worker 63