OverView is a toolkit for visualization of distributed systems, and is designed to be generic (that is, able to be applied to many different distributed systems), scalable (that is, to scale up to very large distributed systems), and dynamic (that is, functioning as well online as it does offline).
OverView is written in Java and is designed to work with any arbitrary Java system via a custom unintrusive profiling mechanism and a simple declarative language (called the Entity Specification Language) which describes how to map Java method invocations into a high-level description of visualization events.
Apache's BCEL is used for OverView instrumentation, while Processing is used for rendering graphics.
Please note that OverView requires Java 1.5 to compile and run.
Step 1: Download the latest OverView Binary from the Downloads section.
Step 2: Add the downloaded JAR file and overviewXXX.jar/overview/processing/core.jar to your classpath CLASSPATH=.:/path/to/overviewX.X.X.jar), or by including it every time from the command line. (eg. java -cp .:/path/to/overviewX.X.X.jar).
Step 3: Write an ESL (Entity Specification Language) file, to map Java method invocations into OverView events. Information on ESL can be found in the ESL section.
Step 4: Run java overview.ovi.OverViewInstrumenter as directed on Software Invocation section from the toplevel directory of your project. OverView will use the ESL file to instrument your existing Java bytecode to send the specified events over a port. Other than that, your program remains unchanged.
Step 5: Start java overview.ovp.OverViewPresenter
Step 6: Run your program. Remember to point the -DovHost option to the host and port where your OVD is running.
Note: You may invert steps 5 and 6 while adding -DovPause as a command line option when you execute your program. Your program will wait for an instance of OVP to be run before executing.
OverView comes with examples for you to test before using it on your own programs.
Make sure you have an instance of OverView Daemon running, to relay events. To start one use:
java overview.ovd.OverViewDaemon
Take note of the port that OVD is running on. Then, you should start a client, so you can visualize events as they happen:
java overview.ovp.OverViewPresenter localhost:6060
or
java overview.ovp.OverViewPresenter localhost:6060
Note: You may use -t as a command line option to start OVP Force Directed Module.
replacing, of course, localhost with whatever particular host you're running OverView on. This should open an empty window that will display events. Finally, run your program:
java -DovHost=localhost:6060 overview.examples.fibonacci.Fibonacci 5
You should begin to see a visualization of the sequence of Fibonacci numbers being calculated recursively.
There is a shell script available with an OverView release called compile, in the topmost directory of the release. The script will compile OverView itself and instrument the included examples. Additionally, if you merely wish to remove all Java binaries, you can execute compile clean to do so.
The usage for OVI, OVP, and OVD are simple:
However, when OVI instruments Java programs, those programs are given several extra command-line options. They are given below.
You will be able to find examples of the specification files in the OverView distribution. ESL files use the (.entity) extension and the following grammar:
Create a class in package overview.ovp.viz and name it <Myvisualization>Visualization.java (e.g. ForceVisualization.java)
Implement the overview.ovp.viz.Renderer interface. This interface contains the essential handle (String[] event), unhandle (String[] event) and draw() methods. These methods allow the visualization to receive events from the OverViewDaemon (OVD) and render graphics using Processing.
Modify overview.ovp.viz.Visualization.setup() and the class's attributes to include your visualization in the selection structure. This will allow the OverViewPresenter (OVP) to point to your visualization.
Run OverView as described in the Software Invocation section.
Q. My entity specification file should be correct... but nothing is happening! What could go wrong?
A. A few things could be happening. First, you should check and make sure that every method or field you're using in OverView is public: if it isn't, it will not be properly instrumented. Secondly, make sure you're using fully qualified class names for every object you reference: a common mistake is to write String instead of java.lang.String!
Q. How can I be sure that OverView is instrumenting my program?
A. Make sure OverView lists every method you're trying to instrument, along with a message saying "instructionHandles.length: 1," or something similar. Otherwise, OverView is not correctly instrumenting your file.
Q. Help! OverView is sending two (or more) of the same event at once!
A. Make sure you recompile your Java code before reinstrumenting it, otherwise OverView will have placed two (or possibly more!) event-sending triggers into your methods!
Also, it's worth checking to make sure you didn't instrument two different methods (that get called very near to each other) that do the same thing.
Q. I run OverView, and the graphical output makes no sense... the topology doesn't look anything like it should. Am I doing something wrong?
A. The most common problem that this results from is events being sent before the visualizer is run, causing no knowledge of proper nesting (since creation messages are generally sent before anything else happens).
The way to fix this is to always adhere to the proper order in running your program: event sinks must always exist before event sources, or else events will get lost. (In the case of SALSA programs, this means starting OVP before your theaters. If in doubt, restart your theaters.)