Scalable Simulation Framework
Raceway Views Animation User Guide
Part I: Overview
     Getting Started
     Raceway Views Concepts
     Working with the Raceway Views Tool
PART II: Network Visualization
PART III: Animation of Network Records

Raceway Views is a software tool for:

  1. visualization and editing of graphical representation of large network configurations, including navigation in large hierarchical networks,
  2. animation of network displays driven by distributed net measurement data streams, and animated plotting of time series.

Several graphical animation examples are in the "animation" directory. Consult the makefiles to see how the animations are run, and examine the DML configuration files to see how graphical annotation attributes are used.

PART I: Overview

Getting Started

Installation

Jarfile lib/raceway.jar contains the latest builds of Raceway packages: SSF, DML, and Views. It can be dropped into an existing SSFNet distribution, also in the "lib" subdirectory, replacing the copy of raceway.jar that you may have received as part of SSFNet.

Several graphical animation examples are in the "animation" directory. Consult the makefiles to see how the animations are run.

Starting the Raceway Views Tool

The simplest way to view and edit the graphical properties of a network specification, assuming you've installed Raceway in /usr/local/raceway:

         java -classpath /usr/local/raceway/lib/raceway.jar RacewayViewer yourfile.dml

A basic Raceway Views window will contain two panels: a graphical network editor on top and a DML browser on the bottom. When data streams are loaded as well, the window divides into four panels: network editor and DML browser on the left, and a stream display and stream control panel on the right. (There is sometimes an additional stream option contorl panel on the right as well.)

You may find that you need to resize the tool window and/or interactively adjust the dividers between the panels.

TroubleShooting

Most problems you face with "class not found" errors will be related to problems with your CLASSPATH environment variable, or with the paths you pass to Java via the -classpath command line argument.

To minimize problems, first make sure your CLASSPATH environment variable is clean and tidy, free of references to obsolete jarfiles and directories. Ideally, you might want to start with an empty CLASSPATH and write Makefiles that pass the -classpath argument to Java. This can save a lot of headaches.

To make sure the new raceway.jar is picked up first, put it at the beginning of your classpath:

         % echo $CLASSPATH
         /usr/local/raceway/lib/raceway.jar

Raceway Views Concepts

About Raceway Views

Raceway Views is a software tool for:

  1. visualization and editing of graphical representation of large network configurations, including navigation in large hierarchical networks,
  2. animation of network displays driven by distributed net measurement data streams, and animated plotting of time series.

The network configuration data used by Raceway Views are in the DML database format, that is the very same format that is used in SSFNet.

Sidebar:   DML is a simple database format particularly well suited
            for use in system configuration applications. In short,
            a DML configuration can express a hierarchy of configuration
            attributes (key-value pairs) for recursive configuration of
            a system's components.  DML is extensible - it supports
            arbitrary user-defined attributes - and simplifies repetitive
            configuration tasks by attribute inheritance and substitution.
            DML configurations are stored in ASCII and are human-readable.

Network Topology: Visualization, Editing and Navigation

Raceway Views provides the framework for displaying network topology.

For hierarchical networks (designed in DML as a hierarchy of Nets) Raceway Views allows navigation in Net hierarchy. Sub-Nets of large hierarchical Nets can be displayed either in full detail (expanded), or as aggregated "network clouds" (collapsed).

The DML network configurations used by Raceway Views are the same as used in SSFNet, but in addition to logical configuration attributes for Nets, hosts, routers and links they include new graphics attributes specifying the locations, transformations, and rendering styles for Nets and for individual network elements.

One can fully customize in DML the rendering style, including link colors and stroke widths, icon selection and fill color, size and orientation for hosts, routers, and "network clouds".

By construction, the graphically-enabled DML network configurations are backward compatible. Insertion of graphical display specifications to an existing DML file will not change the logical network configuration, and will not change its behavior in a simulation.

Network Animation

Raceway Views also provides the framework for animating network measurement data.

The basic idea of network measurement animation is straightforward: given a network configuration (DML database) with graphics attributes, and a stream of some timestamped network measurement records, animation is achieved by programmatically changing the network display in time in order to quickly reveal the information contained in measurement records.

In Raceway, changing the network display may refer to:

  1. changing the color, size or icon representing a network element, for instance to visualize a change in protocol state in a router,
  2. changing the color or width of network links, for instance to visualize link failures,
  3. drawing paths in the network topology, for instance to visualize the paths computed by routing protocols,
  4. displaying the gliding motion of small packet-like objects along links (bi-directional motion is supported), for instance to show actual packet transmissions, or to visually render bi-directional link utilization,
  5. displaying animated sliding-window time-series histograms of traffic rates, or other plots, possibly in conjunction with other network display animation.

Other network animation metaphors are possible as well.

The rate of network animation can be controlled by the VCR-like "double arrow" buttons in the Raceway Views window, which double or halve the playback rate. The central button starts and stops the animation.

The animation rate is defined as as a ratio of "network time" to "display time". The "network time" is defined as real (or simulated) time passing in the course of network measurements, and recorded in the timestamps of network measurement records that will be animated. The "display time" is the real "wallclock" time passing in the course of animation playback.

It does not matter whether the timestamps of consecutive network measurements are spaced irregularly, and how far spaced they may be. Raceway Views will attempt to maintain a steady playback rate, regardless.

Ultimately, however, the CPU and memory speed of the machine running an animation, plus the density of records in the trace and the overhead associated with animating each record, will limit the sustainable playback rate. If the time needed for display repainting computations becomes longer than that allowed by the target playback rate, Raceway Views gives visual feedback to the user by flashing the actual playback rate in red, rather than the requested animation rate in black, in the playback controls.

Working with the Raceway Views Tool

This section explains how to work with the various GUI controls in the Raceway Views program.

Raceway Window Layout, Menus and Controls

The Raceway Views window is divided into several split panes, whose partitions can be adjusted by user click and drag. As described in the "Getting Started" section, a basic window will contain two panes - a network editor above and a DML browser below - while a simulation involving streams with have a stream display pane and 2 different stream contol panes added to the first two panes. In this case, the original network editor and DML browser just move to the left and the new stream display and control panes take up the right half of the screen.

The top left pane in the Raceway Views window, or simply the top pane if streams aren't included, contains the network topology renderer - or 'net display'. This pane graphically displays the network that your DML file has described. It can be used to either edit the visual network or to animate it in playback mode when a stream is running actions on the network.

Net Display Controls

...the File Menu

The controls for the net display are found in the 'File' and 'Edit' menus located above it. The 'File' menu contains the typical 'About', 'Save' 'Print' and 'Exit' commands which tell you a bit about Raceway Views, saves the current state of your network, prints your net display window, and exits the program respectively. Note that 'Exit' does quit the program without saving.

The other save option under the 'File' menu, 'Save Copy... #', is designed to help you easily create back-up copies or revisions of your progress as you are working. When you select 'Save Copy... #' for the first time, it will give you a popup window for each file so that you can choose a stem name for each (your original file names will be inserted by default). After you choose a stem name, Raceway Views will append "_#.dml" onto the end of those stem names. The number used ( # ) will be whatever number was listed in the menu as 'Save Copy... #'. Raceway Views will use your stem name choices as a basis for all copies that are made as long as the program is open. When you close the program and then restart it, you will need to choose a new set of stem names (again, one for each file). In this way, you can choose a unique stem name for each time you open the program, but can then quickly create copies with unique names because of the index that is iterated after each set of saved copies.

For example, suppose the option under the 'File' menu was 'Save Copy... 0' (meaning you hadn't saved any copies since the program was opened) and you only had one DML file called "myFile.dml". When you select 'Save Copy... 0' a popup window will ask for a stem name choice and will give you "myFile" as the default choice. If you were to select "myFile" as your stem choice, then Raceway Views would create a file called "myFile_0.dml" in the directory where the program is being run (which should be where the original file is located). The next time you go to save copies the menu option will be 'Save Copy... 1' and the file created will be "myFile_1.dml". The next time it will be "myFile_2.dml", and so on. This way you can continually save copies during a given session without the problem of trying to overwrite files. You will need to choose different stem names, however, to prevent conflicts between each time you reopen the program. You may choose any stem name you like, but please do not include ".dml" in your choice as this will create problems if you later try to open these file copies. Your original DML files should not be affected by the 'Save Copy... #' function. You will need to use the regular 'Save' option to change those.

If the file that 'Save Copy... #' is trying to create already exists, it will not overwrite that file, but will stop and tell you that an error occurred. Upon completion, the program will tell you how many files were successfully copied (which, if there were no conflictions, should be then number of all your DML files for that particular simulation.) To open these revisions, you will have to set up your code to specifically open these files rather than your original DML files.

...the Edit Menu

The main controls for editing the visual display of your graph are found under the 'Edit' menu. Selecting 'Show ToolBox' will give you all of the functions of the Edit menu in a seperate, movable ToolBox window. Choosing 'Hide Toolbox' from the 'Edit' menu will remove the Toolbox. Moving the mouse over many of the buttons in that ToolBox will give a tip saying which function that button executes.

The 'Select' option allows you to select one or more nodes in the graph to perform some function on. While still in 'Select' mode you can move the selected nodes around in the display window. In order to move more than one node, you will need to hold down the 'Shift' key as you select nodes, and after the final node has been selected release the 'Shift' key while keeping the mouse pressed. You will not be able to move the nodes while the 'Shift' key is pressed, but keeping the mouse pressed while releasing that key will keep you from losing your selected group.

You can change to 'Scale' mode to scale the size of those nodes by clicking anywhere and dragging the mouse towards or away from the first node you selected. If you wish to scale the entire graph, using 'Zoom' would be the best option.

You can also change to 'Rotate' mode to rotate those nodes. Click anywhere to set a bull's eye focal point to rotate around and then click on any selected node and drag it to rotate it around that focal point.

The last of the radio button options, 'Zoom', is for scaling the size of the entire graph. This function works just like the 'Scale' function, but automatically selects the entire graph rather than just scaling part of it.

The 'Refresh' action repaints the entire net display, and the 'Center' action basically places your uppermost graph node at the top of the screen and your leftmost node at the left edge of the screen. The 'Restore' option returns your graph to the form it was in when you last saved - either by using 'Save Copy... #' or the regular 'Save' function.

The 'Commit' command propogates all of the changes you just made in one Net to all of the other identical Nets. This is useful when you are working with a large Net that is composed of many copies of smaller subnets. You can go into the subnet, edit its layout, and then choose 'Commit' to propogate those same changes to all of the other identical subnets. 'Commit' does not save the changes to your DML files, however. You will later need to choose 'Save' in order to do that.

If you have a subnet highlighted in your network graph, you can choose the 'Open Selected Net' (or 'Open Net'->'Open Selected Net' in the Toolbox) to view that subnet directly as though it were the only Net. Nets that have been previously opened will be kept in a list just below the 'Open Selected Net' menu item in the order that they were opened. In this way you can jump between subnets and enclosing nets to easily edit different sections of your overall network graph. Note that, while viewing a larger enclosing Net, pressing CTL and clicking on a node that is a member of a subnet will cause that subnet to "collapse" and be replaced by a cloud icon. Pressing CTL while clicking on this cloud will expand the subnet to its original form again.

Note the blue plus sign that is found in the bottom-right corner of the Net Display pane. This can be clicked to have this pane take up the entire Raceway Views window, and the minus sign that replaces it can be clicked to minimize the pane back to its original size.

The other Raceway Views Panes

Just below the net display pane, there are one or more tabbed panes containing the input DML network configuration files. These are the same DML files that you would run for SSFNet simulations. Note that whenever you click on a node in the graph above, the start of the corresponding DML code for that node or subnet will be highlighted.

If streams have been added to animate the simulation, the Raceway Views window will be divided in half vertically and three more panes will be present on the right side. A special stream animation options control pane with one or more tabs occupys the upper-right corner, a display of the actions of the stream is found below that, and lastly the stream playback control panel is found in the bottom-right corner.

The special animation option controls for the pane in the upper-right corner are set by a class you will write that subclasses java.awt.Component. This sets both which special controls are available and which are selected by default. Further details about this are found towards the end of the "Animation of Network Records" section.

The stream action display essentially gives a list of all the actions that the animation of the simulation will run through. A yellow arrow and read box mark the action that the simulation is currently at.

Finally, the stream control panel at the bottom is basically just a VCR controller for your simulation. The far-left button jumps you back to the start of the simulation, the left-pointing double-arrow button halves the speed of the simulation, the middle button starts or pauses the simulation (depending on if it is running), the right-pointing double arrow button doubles the speed of the simulation, while the right-most button jumps your simulation ahead to the next "significant" action or record in your simulation. You will deal with these actions with the Raceway and Stream classes described a bit more later on in the tutorial.

PART II: Network Visualization

How to add graphics to existing DML files

Raceway Views editing capabilities allow you to add graphics attributes to existing DML network configurations in two steps:

  1. loading a non-graphic DML network to the Views display will cause an automatic insertion of default graphics attributes, and will generate certain default placement of network nodes. Imported Nets will be displayed in "collapsed" mode.
  2. You can then employ the familiar select and drag, scale, rotate, etc. operations to place the hosts, routers and Nets you desire, and finally save the DML files to finalize your changes. Editing of nested hierarchies of Nets is simplified by the capability of visual navigation in a Net hierarchy - selecting a sub-Net (see "Working with the Raceway Views Tool") allows you to open it for editing as if it were a toplevel Net, one level after another.

This Raceway release does not provide automatic network graph layout, with the exception of providing a default layout for a DML network configuration that does not yet have any location attributes for hosts, routers or sub-Nets.

In general, for large nontrivial graphs (i.e. not having some simple property such as being a tree or a DAG) the automatic graph layout algorithms tend not to work very well anyway.

A practical solution for large networks is to exploit the Net hierarchy, as in step 2, in order to limit the layout complexity at each hierarchy level to editing a graph of aggregated Nets and any non-aggregated hosts, routers and LANs.

Once a network has graphics attributes, its appearance can be changed again by using the controls described in "Working with the Raceway Views Tool".

The graphical annotation attributes follow the hierarchy of Nets: the choice of top-level Net rendering style is the default used by all sub-Nets (called "imported Nets" in SSFNet). However, a sub-Net, host or router can override all or some of the inherited rendering specification attributes, and in case of modified attributes of a Net, they in turn become the default for its own sub-Nets.

Network Graphics Attributes

A single DML configuration file is used to launch a Raceway Views window. It contains pathname(s) of the network configuration DML file(s), and optionally the network record stream file and Player to be used in an animation.

Example:

Suppose you launch the RacewayViewer with the shell command:

      java -classpath $(MY_CLASSPATH) 
        RacewayViewer network_file_1.dml       # one or more config files
           -s my_data.dat                      # optional, at most one
           -p My_Player                        # optional
           -start 30 -stop 10000               # optional

File pathnames are always relative to the RacewayViewer's current working directory.

First, RacewayViewer loads the specified DML file(s), creating a single runtime DML Configuration database object.

Second, if the -s option is provided, a record stream will be loaded from the specified file. Every user-defined subclass of Stream.Player named with a -p option will be instantiated, and the stream will be "played" through them. If the start/stop options are provided, they define the timestamp range for records to be played; otherwise, the entire stream is played.

A subsequent edition of this tutorial will describe the Graphics DML attributes. For now, consult the examples in animations directory to see most of the possibilities.

Interactive Network Layout Editing

Once a network is displayed in the Renderer, its apperance can be interactively modified by selecting operations from the Edit menu.

The File menu "Save" will write the edited configuration changes to the DML files. The "Save Copy... #" option will save your edited configuration in seperate DML files with the original names but with the listed number inserted. Again, consult the "Working with the Raceway Views Tool" for descriptions of these controls.

PART III: Animation of Network Records

TIP:The best way to get up to speed with animation is to read the 
       source code of the examples provided with the Raceway distribution.

How to animate network data

Raceway Views provides two Java classes for programmatic animation of displayed networks: the Raceway class and the Stream class. See the javadoc documentation for details.

The Raceway Class

... allows you to programmatically change the rendering style of hosts, routers, links and Nets that are visible in the display window.

The basic idea is as follows: a user program can get a reference to any Net, host or link object that is currently visible by using this Net's, host's or link's topological address (NHI) in the network configuration database.

Once a reference to a visible object is obtained, that user program can change the object's drawing properties such as color, line stroke width, or icon or Image selection, etc., using the appropriate methods in the Raceway class.

Note the phrase "currently visible" in referring to network elements in the paragraph above. Raceway Views allows users to interact with the display in the editing mode, and in particular a user might collapse or expand a Net to see the animation in required detail. Under such conditions, a given host may not be "visible" if it is a member of a collapsed Net, and the animation author must take this into account.

In principle, this low-level programming interface could be sufficient to create arbitrarily complex animations as user programs; however the user program would then have to be responsible for the timing of rendering changes that make up an animation. This method is not recommended.

To simplify the development of animations based on timestamped network measurements, Raceway Views automatically provides proper timing of animations if the measurement records are processed by a user-derived subclass of the Stream class that converts network measurement records to concrete rendering changes.

The Stream Class

... allows you to drive Raceway network animations at a steady rate under the control of VCR-like control buttons, and in addition allows you to examine the records themselves for drill-down analysis. This requires using a stream of time-stamped network measurement records as input to Raceway animations.

Sidebar:   A network record stream format is described in the documentation
            of the inner class Stream.Record. Each record consists of a 
        standardized header (timestamp, originating network element 
        address, record type, total record length in bytes), followed 
        by record-type-specific measurement data bytes.

            A Record is thus analogous to that described in the documentation 
            of the package SSF.Util.Streams. Therefore, a properly instrumented 
        SSFNet simulation can generate one or more streams of measurement 
        records from a variety of measuring probes placed at different 
        network locations.

Given a network DML configuration and a record stream file containing the network measurement data, the procedure to animate the data is conceptually fairly straightforward.

The Raceway Views window has three user-configurable java.awt Components that participate in record animation.

  1. The first is the network renderer. It shows the network topology using the network configuration DML file(s). A user controls:
    • the background color (which may include color gradients for better effect), by setting the .background attribute.
    • the appearance of network elements and links, by using the network DML graphics attributes for static display on startup, and the Raceway class methods for dynamic repainting.
  2. The second record animation component is the running display of a textual representation of network records. A user may specify how a record of a given type is to be shown using the facilities of AttributedString.
  3. The third record animation component is a java.awt.Component that a user can write to display any special controls for this Player, such as a set of buttons to interactively select which records should be animated.

In the current versions of Raceway Views, these controls will appear in the StreamPlayer tool in a tabbed pane.

Specifically, this is what a user should do:

  1. First, write a class implementing the Stream.Player interface, implementing the method "play(Stream.Record r)". When "play(r)" is called by the Raceway Views with the next Stream.Record reference, it should parse the record and upon examining the appropriate record fields it should change the rendering of appropriate network component in the network display panel. To change the rendering, use any of the methods made available by the Raceway class or its subclasses that are provided in the distribution. Note that a test should be made if the graphical element to be changed is "visible" as explained above. The visibility should guide the animation implementation to choose a different metaphor to visualize changes depending whether the network element is visible, or is hidden inside a collapsed Net.
  2. Similarly, implement the method "describe(Stream.Record r)". When "describe(r)" is called by Raceway Views with the next Stream.Record reference, it should parse the record and upon examining the appropriate record fields it should return a string that represents the record by an ascii string. For example, if a record were an IP packet from a tcpdump stream, an animation developer might choose to display the source and destination IP addresses. This string will be displayed in the lower right-hand tool panel, and highlighted if the corresponding record's timestamp is at the current animation time. In the current version of Raceway Views the record strings scroll through the tabbed pane on the right of the network topology display, just above the VCR-like animation playback controls.
  3. Finally, write a class subclassing java.awt.Component to contain any special controls for the animation. In the current version of Raceway Views, this component appears in the tabbed pane just above the record string display. The Raceway framework will obtain a reference to this control component by calling the getControls() method of the user's Stream.Player.