plast-lab / HeapDL

Heaps Don't Lie! Analyzes standard JVM and Android heap snapshots to improve the completeness of program analysis tools such as Doop.

HeapDL

Heaps Don't Lie! Published in PACM PL OOPSLA (2017) (pdf)

HeapDL is integrated with the Doop pointer analysis framework, however it is also available as a standalone tool and as a library.

Using HeapDL in standalone mode

Method 1 (JAR):

$ ./gradlew fatjar
$ java -jar build/libs/HeapDL-all-1.1.10.jar file.hprof --out output-dir

Method 2 (native-image):

$ ./gradlew nativeImage
$ build/bin/heapdl file.hprof --out output-dir

Using HeapDL as a library

repositories {
    jcenter()
    maven { url "https://jitpack.io" }
}
dependencies {
    compile 'com.github.plast-lab:HeapDL:1.1.9'
}

The basic class when using HeapDL as a library is heapdl.core.MemoryAnalyser (and the heapdl.io.HeapDatabaseConsumer interface that can be implemented by clients). For an example of using HeapDL as a library, see class heapdl.main.Main.

Generating a heap snapshot for use with HeapDL

OpenJDK/IBM JDK (Java <= 8)

To take a heap snapshot of a running program (Program.jar) on program exit, run:

java -agentlib:hprof=heap=dump,format=b,depth=8 -jar Program.jar

It will produce a java.hprof file and then you can run HeapDL with:

java -jar build/libs/HeapDL-all-1.1.9.jar java.hprof --out output-dir

OpenJDK (Java 9-10)

To take a heap snapshot of a program (Program.jar) on program exit, first build the heapDump-agent and then run:

java -javaagent:heapDump-agent/target/theLastDump-1.0-SNAPSHOT-jar-with-dependencies.jar -jar Program.jar

The heap snapshot for Java 9-10 doesn't contain stack traces. It will only produce a heap-dump.hprof and then you can run HeapDL with:

java -jar build/libs/HeapDL-all-1.1.9.jar heap-dump.hprof --out output-dir

OpenJDK (Java >= 11)

To take a heap snapshot of a program (Program.jar) on program exit, first build the heapDump-agent and the stackTraces-agent and then run:

java -javaagent:heapDump-agent/target/theLastDump-1.0-SNAPSHOT-jar-with-dependencies.jar -agentpath:stackTraces-agent/libStackTracesAgent.so=sampling=512kb,depth=8 -XX:+UnlockExperimentalVMOptions -XX:+UseEpsilonGC -jar Program.jar

For the stackTraces-agent you can configure the sampling rate and the depth of the stack traces by using the optional arguments.

The above command will produce a heap-dump.hprof file and a stackTraces.csv and then you can run HeapDL with:

java -jar build/libs/HeapDL-all-1.1.9.jar heap-dump.hprof --stackTraces stackTraces.csv --out output-dir

Android

To take a heap snapshot an Android app running on a device (or emulator) bridged by adb, run the following (APP_PACKAGE/MAIN_ACTIVITY are the names of the application package and the main app activity to launch respectively):

# Start app.
adb shell am start --track-allocation $APP_PACKAGE/$MAIN_ACTIVITY

# When ready, take heap snapshot (we assume $2 is the PID field of ps).
adb shell am dumpheap `adb shell ps | grep $APP_PACKAGE\$ | awk '{print $2}'` /data/local/tmp/$APP_PACKAGE.android.hprof

# Download and convert.
adb pull /data/local/tmp/$APP_PACKAGE.android.hprof .
hprof-conv $APP_PACKAGE.android.hprof $APP_PACKAGE.hprof