rb-wartslib: Ruby Warts Library

What is it?

This is a Ruby extension for reading/writing warts files. Warts files are output by scamper, a tool for performing large-scale traceroute- and ping-based network measurements. You can also use this extension to read (but not write) arts++ files produced by skitter.

This extension only provides a thin wrapper around the C-language routines in scamper for reading/writing warts files. But this is all you need to write pleasant little Ruby scripts that compute various statistics about collected traces, convert IP paths to AS paths, and perform myriad other processing for which, let's be honest, life is too short to be writing in C. Write your analysis scripts with rb-wartslib, and with a Zen-like peace, spend your newly discovered free time with your friends, family, and your neglected small furry pet animals.

But Ruby is slow!

Yes, it is. But it is also fast enough. For example, some of the sample Ruby analysis scripts only take 1½ to 2 times longer than an equivalent written in C/C++ because all the warts I/O is done in C code. If you're computing the hyperbolic Lagrangian bleibenvalues, then it might be a bit slow with Ruby, but what are computers for after all? More importantly, it's much easier to write correct code with Ruby than C, and correctness is far more important than speed with data analysis.


Although you can use this extension to write out trace data to warts files, you can't use this extension itself to create completely new traces in memory--that is, you can only write out traces you've read in from a file. Furthermore, any read-in data is immutable, with a few careful exceptions, because the principal purpose of this extension is to support the analysis of existing data rather than the creation of new data. The ability to write out (unmodified) traces is still useful for filtering out traces and for re-organizing traces into a different set of files (for example, into daily files, or into separate files by the type of probing method used).


You can install rb-wartslib directly from the online RubyGems repository (that is, without manually downloading the gem file) with

  $ sudo gem install rb-wartslib


The rb-wartslib gem directly incorporates the source code of scamper-cvs-20110803. If you wish, you can install rb-wartslib with a newer version of scamper, but there is no guarantee that rb-wartslib will work with a newer (or older) scamper version. Download and build the version of scamper you want, and install it somwewhere. Let $SCAMPER stand for the absolute path to the directory where scamper is installed (not the build directory). Now install rb-wartslib with

  $ sudo gem install rb-wartslib -- --with-scamper-dir=$SCAMPER


Start by reading the tutorial, which discusses fundamental concepts and covers most of the common uses. Then look over the sample analysis scripts. For a more in-depth documentation of the Ruby classes, see the reference documentation.

The sample scripts are also included in the bin subdirectory of the rb-wartslib distribution file. To find them on your system, execute the following after installing rb-wartslib:

  $ gem contents rb-wartslib


rb-wartslib is written and maintained by Young Hyun as a part of CAIDA's work on the Archipelago Measurement Infrastructure. You may contact him at youngh AT caida DOT org.

Please direct scamper questions, including problems building it, to Matthew Luckie:

   mjl (squigglyatthingie) wand (period) net (period) nz


The rb-wartslib binding code is licensed under GPLv2 or later, but this binding must link with scamper, which is licensed under GPLv2 only (no later). Therefore, when your own Ruby program makes calls into rb-wartslib (that is, "links" to rb-wartslib), then rb-wartslib is effectively under GPLv2 only, so your client program must be GPLv2 compatible. However, if you merely re-use any of the rb-wartslib source code in your own programs (but none of the scamper source code), then the license is GPLv2 or later. For example, if you wish to use the rb-wartslib source code as a template for writing an extension of your own (that provides a binding to something else), then the code is licensed under GPLv2 or later.

If you don't distribute your client program, then the requirements of the GPL do not apply to your client program. In particular, if you write an internal tool used only in your organization, then it does not have to be released under the GPL to use rb-wartslib; it can have whatever license you choose. This freedom is intentionally allowed by the GPL.


The design of these web pages draws on one of the styles used by the TWiki wiki tool.