Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jrudolph/fjp-trace

Instrumented JSR166 ForkJoinPool + trace renderer
https://github.com/jrudolph/fjp-trace

Last synced: 25 days ago
JSON representation

Instrumented JSR166 ForkJoinPool + trace renderer

Awesome Lists containing this project

README 

        
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 



 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.