README.md
1# Titrace
2
3Titrace is a bytecode instruction tracing tool that uses JVMTI and works on both ART and the RI.
4
5# Usage
6### Build
7> `make libtitrace` # or 'make libtitraced' with debugging checks enabled
8
9The libraries will be built for 32-bit, 64-bit, host and target. Below examples assume you want to use the 64-bit version.
10### Command Line
11#### ART
12> `art -Xplugin:$ANDROID_HOST_OUT/lib64/libopenjdkjvmti.so -agentpath:$ANDROID_HOST_OUT/lib64/libtitrace.so -cp tmp/java/helloworld.dex -Xint helloworld`
13
14* `-Xplugin` and `-agentpath` need to be used, otherwise libtitrace agent will fail during init.
15* If using `libartd.so`, make sure to use the debug version of jvmti.
16#### Reference Implementation
17> `java -agentpath:$ANDROID_HOST_OUT/lib64/libtitrace.so helloworld`
18
19Only needs `-agentpath` to be specified.
20### Android Applications
21Replace __com.littleinc.orm_benchmark__ with the name of your application below.
22#### Enable permissions for attaching an agent
23Normal applications require that `debuggable=true` to be set in their AndroidManifest.xml.
24
25By using a *eng* or *userdebug* build of Android, we can override this requirement:
26> `adb root`
27> `adb shell setprop dalvik.vm.dex2oat-flags --debuggable`
28
29Then restart the runtime to pick it up.
30> `adb shell stop && adb shell start`
31
32If this step is skipped, attaching the agent will not succeed.
33#### Deploy agent to device
34The agent must be located in an app-accessible directory.
35
36> `adb push $ANDROID_PRODUCT_OUT/system/lib64/libtitrace.so /data/local/tmp`
37
38Upload to device first (it gets shell/root permissions).
39
40> `adb shell run-as com.littleinc.orm_benchmark 'cp /data/local/tmp/libtitrace.so /data/data/com.littleinc.orm_benchmark/files/libtitrace.so'`
41
42Copy the agent into an app-accessible directory, and make the file owned by the app.
43
44#### Attach agent to application
45
46##### Option 1: Attach the agent before any app code runs.
47> `adb shell am start --attach-agent /data/data/com.littleinc.orm_benchmark/files/libtitrace.so com.littleinc.orm_benchmark/.MainActivity`
48
49Note: To determine the arguments to `am start`, launch the application manually first and then look for this in logcat:
50
51> 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
53##### Option 2: Attach the agent to an already-running app.
54> `adb shell am attach-agent $(pid com.littleinc.orm_benchmark) /data/data/com.littleinc.orm_benchmark/files/libtitrace.so`
55
56### Printing the Results
57All 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
59> `kill -SIGQUIT $(pid com.littleinc.orm_benchmark)`
60
61Will initiate a dump of the agent (to logcat).
62
63