1# tiallocsample
2
3tiallocsample is a JVMTI agent designed to track the call stacks of allocations
4in the heap.
5
6# Usage
7### Build
8>    `m libtiallocsample`
9
10The libraries will be built for 32-bit, 64-bit, host and target. Below examples
11assume you want to use the 64-bit version.
12
13Use `libtiallocsamples` if you wish to build a version without non-NDK dynamic dependencies.
14
15### Command Line
16
17The agent is loaded using -agentpath like normal. It takes arguments in the
18following format:
19>     `sample_rate,stack_depth_limit,log_path`
20
21* sample_rate is an integer specifying how frequently an event is reported.
22  E.g., 10 means every tenth call to new will be logged.
23* stack_depth_limit is an integer that determines the number of frames the deepest stack trace
24  can contain.  It returns just the top portion if the limit is exceeded.
25* log_path is an absolute file path specifying where the log is to be written.
26
27#### Output Format
28
29The resulting file is a sequence of object allocations, with a limited form of
30text compression.  For example a single stack frame might look like:
31
32```
33+0,jthread[main], jclass[[I file: <UNKNOWN_FILE>], size[24, hex: 0x18]
34+1,main([Ljava/lang/String;)V
35+2,run()V
36+3,invoke(Ljava/lang/Object;[Ljava/lang/Object;)Ljava/lang/Object;
37+4,loop()V
38+5,dispatchMessage(Landroid/os/Message;)V
39+6,handleMessage(Landroid/os/Message;)V
40+7,onDisplayChanged(I)V
41+8,getState()I
42+9,updateDisplayInfoLocked()V
43+10,getDisplayInfo(I)Landroid/view/DisplayInfo;
44+11,createFromParcel(Landroid/os/Parcel;)Ljava/lang/Object;
45+12,createFromParcel(Landroid/os/Parcel;)Landroid/view/DisplayInfo;
46+13,<init>(Landroid/os/Parcel;Landroid/view/DisplayInfo$1;)V
47+14,<init>(Landroid/os/Parcel;)V
48+15,readFromParcel(Landroid/os/Parcel;)V
49=16,0;1;2;3;1;4;5;6;7;8;9;10;10;11;12;13;14;15
5016
51```
52
53Lines starting with a + are key, value pairs.  So, for instance, key 2 stands for
54```
55run()V
56```
57.
58
59The line starting with 0 is the thread, type, and size (TTS) of an allocation.  The
60remaining lines starting with + are stack frames (SFs), containing function signatures.
61Lines starting with = are stack traces (STs), and are again key, value pairs.  In the
62example above, an ST called 16 is the TTS plus sequence of SFs.  Any line not starting
63with + or = is a sample.  It is a reference to an ST.  Hence repeated samples are
64represented as just numbers.
65
66#### ART
67>    `art -Xplugin:$ANDROID_HOST_OUT/lib64/libopenjdkjvmti.so '-agentpath:libtiallocsample.so=100' -cp tmp/java/helloworld.dex -Xint helloworld`
68
69* `-Xplugin` and `-agentpath` need to be used, otherwise the agent will fail during init.
70* If using `libartd.so`, make sure to use the debug version of jvmti.
71
72>    `adb shell setenforce 0`
73>
74>    `adb push $ANDROID_PRODUCT_OUT/system/lib64/libtiallocsample.so /data/local/tmp/`
75>
76>    `adb shell am start-activity --attach-agent /data/local/tmp/libtiallocsample.so=100 some.debuggable.apps/.the.app.MainActivity`
77
78#### RI
79>    `java '-agentpath:libtiallocsample.so=MethodEntry' -cp tmp/helloworld/classes helloworld`
80