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.
The quickest way to start using OverView is to simply download the latest OverView binary, above. It will download a .jar file, which you should place in a convenient location.
Then, all you need do to start using OverView is to ensure that the .jar file is in your Java classpath, either by placing it in your CLASSPATH environment variable (eg. CLASSPATH=.:/path/to/overviewX.X.X.jar), or by including it from the java command line (eg. java -cp .:/path/to/overviewX.X.X.jar).
Now, using OverView is a two-step process. First, you need to write an Entity Specification Language file, which is used to map Java method invocations into OverView events. Once writing it, you should run java overview.ovi.OverViewInstrumenter on that ESL file, from the toplevel directory of your project. OverView will examine the ESL file and instrument your existing Java bytecode to send events over a port. Other than that, your program remains unchanged. The second step consists of running your program and starting java overview.ovp.OverViewPresenter to listen to it. This is easiest to do by starting your java program with the -DovPause command line switch (so that it will wait for OVP before executing).
If you would like to test OverView to ensure that it works, it comes with a couple test programs. Before doing anything, you will need an OverView Daemon running, to relay events. To start one, try:
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
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 8
You should begin to see a visualization of the sequence of Fibonacci numbers being calculated recursively.
Compilation is managed through a simple shell script, 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.
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.)