Elephant Tracks 0.x

Elephant Tracks is a garbage collection tracing tool for java programs. For an arbitrary java program, it will produce a trace file with the following features:

Produces an in-order trace of object allocation, death, method entry, method exit, and pointer update events.
Time measured by method entry/exit
Uses the Merlin Algorithm by Hertz et. Al to compute object death times accurate to the nearest method call/exit, described here
Works on most java code (native methods not currently supported)
Connects to any JVM that supports JVMTI

Beta release available for download

Publications

Elephant Tracks: Portable Production of Complete And Precise GC Traces. ISMM 2013 (to appear).
Tool Demonstration: Elephant Tracks: generating program traces with object death records. PPPJ 2011. Available here

Building it

Elephant tracks uses a combination of bytecode rewriting and JVM callbacks. The ET bytecode rewriter is written in Java using the ASM bytecode analysis and transformation library. Download verion 3.1 of the ASM jar file. JVM callbacks are implemented in C++ as a JVMTI (JVM Tool Interface) agent. The agent is compiled as a dynamic library (a .so) and loaded by the JVM at runtime (see "Running ET" below).

To build the system, first edit Makefile.inc and set the various variables appropriately. INSTALL_DIR should refer to a directory that will hold the ET bytecode rewriter jar file and the JVMTI agent .so -- this directory needs to be accessible when the tool is run. ASMJAR and JAVA_PATH should point the ASM jar file and the local Java installation, respectively. Use "make all" followed by "make install" to compile, link, and copy the jar file and .so to the install directory.

On x86_64 you will need to make sure CXXFLAGS and CFLAGS contains the -fPIC option.

Running it

To trace a Java program, run the program as you normally would, but providing the extra JVM arguments that load the Elephants Tracks JVMTI agent and bytecode rewriter. It is helpful to reuse the path values given in the Makefile.inc file. Make sure INSTALL_DIR is in the LD_LIBRARY_PATH.

  java -classpath <other-paths>:$ASMJAR -Xbootclasspath/a:$INSTALL_DIR \
       -agentlib:ElephantTracks=javaPath=$JAVA_PATH:traceFile=<tracefilename>:namesFile=<namesFile>:classReWriter=$INSTALL_DIR/elephantTracksRewriter.jar \
       <class-to-run> <rest-of-args>

Some version of ASM seem to cause trouble, so I've uploaded a known to work jar here.

Other useful command line options:

useOptimizer=T

Turns on the optimized version of the byte code instrumenter. Doesn't make things go much faster, but will inject fewer byte codes, which is useful if so many are injected that the limit is exceeded (needed to run the full dacapo suite).

Trace file format

The trace file produced by Elephant tracks consists of a sequence of events, one per line, in time order. Each entry begins with a single character that indicates the type of event, followed by one or more arguments. Numeric arguments are all in hex (without the "0x").

Note: thread IDs need not have any special meaning, but in ET they happen to be the object IDs of the corresponding java.lang.Thread objects.

Allocation:

A <object-id> <size> <type> <thread-id>

The new object has ID object-id, which is used to refer to the object in later events; the size in bytes; the type (a Java type as a string); the ID of the allocating thread.

Death:

D <object-id>

Pointer update:

U <old-target-id> <object-id> <new-target-id><thread-id>

A field (currently, unspecified) in the object with ID object-id is changed from pointing to old-target-id to point to new-target-id, and this occured in thread-id.

An object-id of 0 indiacates that this is an update to a static field.

Method entry:

M <method-id> <receiver-object-id> <thread-id>

A call to the method method-id with receiver object receiver-object-id in thread thread-id.

A origin receiver of 0 indicates that this was a static method

Method exit:

E <method-id> <receiver-object-id> <thread-id>

Return from method method-id with receiver object receiver-object-id in thread thread-id.

A receiver of 0 indicates this was a static method.

Names File Format

The names file matches various names from the program to numbers used in the trace. The names file used is control with the namesfile=<file name>.

Method name:

N <method-id> <class-name> <method-name> <signature>

Field name:

F <I|S> <fieldId> <name> <classId> < className> <desc>

Class name:

C <class-id> <class-name> <super-id>

Instance name:

I <class-id>

Updated May 13, 2013