This README was last updated (partially) for Traces 1.4.1 on March 1, 2002. See for later versions of the program http://www.tbm.tudelft.nl/webstaf/janb/software/index.html. There is a menu options (under Help) in the Traces program to check the web site for new versions.
This is the readme file of Traces, a Java program that can read traceroute data of the RIPE test-traffic project, stored in a database, and generate graph views. These graphs consist of hosts as nodes and links as edges. The graphs can be exported in GraphXML, Otter data format, daVinci data format and Postscript. The GraphXML export module is by far the most developed. The graphs can be simplified by projecting the hosts to their related autonomous systems, and (when delay data is added to the RIPE-TT database) some calculations can be made.
The XML files can be further analysed using the "graaf" python script by Wim Vree, which can be found in the CVS repository.
In order to use this program, you need access to the test-traffic database, or to one of its mirrors. Participants to the test-traffic project get access to this database. Look at the project page for details. There is also a possibility to access the data for scientific purposes.
Get the binary archive traces-1.4.0-bin.tar.gz. Unpack the files in the archive into a directory. You should have the following files:
Use a 1.4 JDK (download from http://java.sun.com/j2se/1.4/) and run the jar file as follows:
java -jar traces.jar
So, what can you do with this program? In this section we will guide you through some of its uses. Before you start, take a look at the Tools/Options dialog. See the section on the Options dialog for instructions. After you filled in at least the Database settings and File locations, you are ready for a first roll. First, click View/Show Log window so that you can see what is going on. Then, click File/Query Database to bring up the Import dialog. Click three times on the up arrow next to "End date" so that the end date reads September 4, 1999. Then click Select and select test boxes 1, 2 and 12, both in the source and destination test boxes. Click OK and you will see that "Subset of boxes" is selected, and that below that appears a line "Src: 1-2, 12; Dst: 1-2, 12" indicating which source and destination test boxes you have just selected. Do not select Use DNS or Read Delays for now, and press OK. This first query may seem to take an unreasonable amount of time, but that is because the program will now set up the autonomous system data cache. Next time, it will only have to read in the AS cache file. When it finishes it prints the number of nodes and edges (IP addresses and links) it has found to the log window and it shows a graph in the main window. The nodes of this graph are placed at random. Click View/Labels/Show Labels to show IP addresses (and host names for the test boxes themselves) in the graph. At the moment, the graph will look ugly: you can try manipulating the graph by hand (click and drag nodes), you can change the curved edges into straight ones (by selecting View/Edge Style/Straight edges) and you can have the graph automatically laid out by choosing View/Layout, choosing "All nodes" in the combo box near the bottom of the dialog and clicking "OK". The graph will be shaken up a bit, but it finally settle into an aesthetically pleasing form.
You have probably been wondering about the collection of sliders next to the main graph. Forget about the "Delay filter" sliders for now: you can only use them when you have read in delay values next to the traceroute data, and these delay values are not in the standard RIPE-TT database. You can use the other two filters, however: the "Degree Filter" sliders let you cut out nodes with a low number of edges (the first slider) and nodes with high number of edges (the second slider). Play with these sliders.
The current threshold value is printed next to the slider. The "Date filter" slider is off by default; switch it on to show only the nodes and edges active at a certain point in time. By using the slider, you can see that the network configuration inside RIPE-NCC was not completely stable in the beginning of September 1999. The combo box currently reading "Hours" determines the minimal step size of the Date filter slider. This can be used to sweep together all measurements within, for instance, one hour or one day.
To be continued....
To be filled in...
--- FIXME: UNFINISHED DOCS
Save/Save AS XML format: Output graph data in XML format
Export Otter (odf) format: Output graph data in Otter format,
with the .odf extension
Export daVinci format: Output graph data in daVinci format,
with an .daVinci extension.
Also produce -nodull files: Remove certain "dull" nodes from the
graphs. Use with care. See source code in
"DelayGraph.java" for details.
The program can generate graphs that contain data from several points in time. In the XML output, the nodes and edges have a "dates" property that contains the dates that the node or edge was active, in Un*x time_t format (seconds since 1970/1/1).
The top part of the dialog selects the date or dates to query. You can specify a start date, an end date and the interval between each point. For instance, if you set the start date to December 1, 1999, 12:00, the end date to December 5, 1999, 12:00 and the interval to 1 day, you will get 5 dates, December 1 at noon, December 2 at noon up to and including December 5 at noon. As a safety valve, you can specify the max number of dates, so that when you set the interval to 1 minute with the start and end date two years apart you never get more than the specified number of dates.
The next section of the dialog selects the testboxes to query. The are three possibilities:
--- FIXME: UPDATE
All test boxes: Use traceroutes from and to all test boxes.
Subset of boxes: Set From Testbox # and To Testbox # to indicate
a range of test boxes, for instance 10 up to and
including 19.
Single trace: Set From Testbox # and To Testbox # to indicate
a single traceroute, for instance take only the
trace from testbox 1 to testbox 9 into account.
To be filled in...
To be filled in...
- The "Show suspicious AS" button prints the IP addresses of which
the AS number hasn't been determined to the Log window
- The "Clean up AS hash" button retries getting AS information of
the IP numbers in the AS cache of which the AS number has not been
determined. Useful after a program update that includes better
AS search facilities.
Perform delay calculations: Experimental, do not use
In this section we will discuss the Options dialog you can find under Tools/Options dialog. After you installed the traces program, you will need to fill in at least the Database setting and File locations.
To be filled in...
to be filled in...
Let me know if you find more! Mail me at janpascal(at)vanbest.org
The program writes a lot of information to the log window. However, it will sometimes pause for a long time, for instance when querying the database. This is normal behaviour and does not have to mean that the program has crashed.
Anonymous CVS:
$ export CVS_RSH=ssh
$ export CVSROOT=:pserver:anonymous@tux.ict.tbm.tudelft.nl:/var/cvs
$ cvs login
(hit Enter when asked for a password)
$ cvs checkout matrix
$ cvs checkout graph
$ cvs checkout traces
$ cvs checkout graaf # for the Graaf python script
Let me know if you have anything to add and would like write access.
You need Sun's JDK 1.4 and GNU make. I use CygWin under Windows NT, so the Makefiles keep track of two sets of pathnames, one in Unix-style
and one in Windows-style. This can be a bit irritating. Get the graph/, matrix/ and traces/ trees, and the needed external jarfiles
(Jama-1.0.1.jar, mysql.jar, jdom.jar, classes.zip). Make sure that you get the latest versions of all source trees.
First, in the graph/ tree, run
$ make config
This will create a default configuration file in config.h. Edit this file.
You will probably need to edit the following variables:
# The path where you installed the Java Development Kit, version 1.4 or higher
JDKPATH=/Java/jdk1.4
# Classpath: tells Java where to find the .jar libraries
# This is mostly the jdom.jar file
CLASSPATH=/Java/jdom.jar
# Where to install the generated JavaDoc API documentation
# You probably won't need this
DOCINSTALLPATH=/cygdrive/w/software/graph/api
Then do
$ make jarfile
to create graph.jar
Go to the matrix/ tree, do
$ make config
there and edit the config.h file. Do
$ make jarfile
to create matrix.jar
Next, go to the traces/ tree and do
$ make config
This will create a default config.h. Edit it.
Do
$ make jarfile
to create traces.jar.
The following relevant targets exist in the Makefile:
compile: Compile all .java files to .class files.
config: Create default configuration file config.h.
jarfile: Create the traces.jar file
version: Create a new Version.java and Version.class using the VERSION
variable, if this has changed
clean: Clean up class files and jar file, also tidy
tidy: Clean up backup files
archive: Create a source distribution archive
bin-archive: Create a binary distribution archive, including
supporting jarfiles
doc: Create javadoc class documentation
doc-install: Copy the docs to the DOCINSTALLPATH
run: Run the main program
test: Run a test program
applet: Try running the applet version. EXPERIMENTAL
cleanup: Remove double entries from the Delays table
import: Import into the Delays table. This needs text representation
of test-traffic root files.
Sun JDK 1.4, http://java.sun.com/j2se/1.4/
JDom, http://www.jdom.org/
Java Matrix, http://math.nist.gov/javanumerics/jama/
mm.mysql, http://mmmysql.sourceforge.net/
jlapack-0.3a, http://www.cs.utk.edu/f2j/download.html
Traces home, http://www.tbm.tudelft.nl/webstaf/janb/software/index.html
Traces API doc, http://www.tbm.tudelft.nl/webstaf/janb/software/traces/index.html
Graph API doc, http://www.tbm.tudelft.nl/webstaf/janb/software/graph/index.html
GraphXML, http://www.cwi.nl/InfoVisu/GraphXML/index.html
RIPE, http://www.ripe.net
RIPE test-traffic, http://www.ripe.net/test-traffic/
mysql, http://www.mysql.com
Jan-Pascal van Best
janpascal(at)vanbest.org
ICT group, Department of Technology, Policy and Management,
Delft University of Technology, The Netherlands
http://www.tbm.tudelft.nl/webstaf/janb/
http://www.ict.tbm.tudelft.nl