jrudolph / fjp-trace Goto Github PK

Instrumented ForkJoinPool implementation
--------------------------------------------------------------

This implementation is based on JSR 166 by Doug Lea. 
The baseline version is available either in JDK 7+, or 
JSR-166 concurrency interest: http://g.oswego.edu/dl/concurrency-interest/

GENERATED DATA (aka FEATURES):

Most of the graphs are showing the progress in time.

 1. *-events.txt.gz: raw event stream
     This is the event stream, sorted by time, and printed in human-readable form.

 2. *-workerState.png: worker states
     This graph should be the most familiar, like the other thread state tracers do.
     The excess of waits and idle threads can highlight either capacity or
     decomposition problem.

 3. *-workerState.txt.gz: worker states (text representation)
     Text trace might be more useful to track event sequence more accurately. While
     raph could show you the big picture, text trace can drill down to individual
     events.

 4. *-workerQueue.png: worker queue state
     This graph infers the remaining elements in each worker queue. Note that
     fjp-trace has no direct measure of queue depth, instead inferring it from the
     fork-exec event pairs. That probably brings some hysteresis into the picture,
     and should be considered when making decisions.

 5. *-exectime*.png: execution time for each subtask
     Exclusive time is the time spent in the task alone, without counting recursive
     invocations. Inclusive time accounts the recursive invocations as well, and so
     it often looks like the "exclusive time" pre-image copied at periodic time
     shifts.

 6. *-externalColors.png: aggregate subtasks by their external task origin.
     This is useful to watch for subtasks interleaves and diagnose fairness
     problems. Also, the graph is rather psychedelic, and can be (but probably
     should not be) used in conjunction with appropriate chemical agents to bring
     the unforgettable experience.

 7. *-subgraphs.png: the decomposition trees in more detail, down to individual 
     traces. You might find more convenient to focus on specific parts with time 
     range. Also, -DtaskTree.detail=true to render event labels.

 8. *-summary.txt: summary statistics for tasks executed

If there is something else sorely needed, don't hesitate to raise the issue.

QUICK START:

 1. Build the distribution
   $ mvn clean install

   This will generate target/fjp-trace.jar, which is the one and only 
   artifact for this project.

 2. Get the trace by running your application with fjp-trace bootclasspath'ed:
   $ java -Xbootclasspath/p:fjp-trace.jar ...

   You should see something like "Using instrumented ForkJoinPool" in stdout, 
   which will tell if bootclasspath was successful. Try to run your application 
   in this mode first, this does not enable any new functionality.

 3. Enable tracing and run again
   $ java -Xbootclasspath/p:fjp-trace.jar -Djava.util.concurrent.ForkJoinPool.trace=true ...

   This will generate trace dump. You can override trace dump location 
   via -Djava.util.concurrent.ForkJoinPool.traceLog=#

 4. Parse the trace:
   $ java -jar fjp-trace.jar -s <trace file>

 You can also use some of the advanced options, see the help:
   $ java -jar fjp-trace.jar -h


CAVEATS:
 * Trace format is not considered to be stable, although it almost never
   changes. Keep that in mind while conducting the experiments spanning days
   of runs: the update to the tracer can invalidate the previous traces.

 * Tracer can generate *lots* of data if FJP is loaded enough. You might want
   to use limit/offset during the trace loading. Asking for limit is almost 
   always safe, while asking for offset may sometimes jeopardize the data, 
   since the data about the past would be lost from the inference.

 * Use from/to time to focus on specific parts of the trace! This will still
   load the entire trace file, and so the data integrity would not be violated.