Ruby-trace is a package used by programmers, testers, server administrators and others to understand what happened during the execution of a Ruby program. It requires programmers to add tracing statements like the following to the code.

$trace.announce "Using alternate capability file '#{chosen}'."

Messages like the following are then printed to the screen, stored in an internal ring buffer, or saved in a log file.

netapp.rb:13:in `initialize'
= announce: Using alternate capability file 'alt.cap'.

I tried to make Ruby-trace as pleasant as Ruby itself. It should be easy to get started, but there is much flexibility for those who need it.

For example, people who use Ruby-Trace for scripts simply need to require one file, scatter a few trace statements through their code, then invoke the program like this:

% ruby-trace myprog.rb

That causes trace output to be printed. When invoked in the normal way, all trace output is suppressed. For these people, Ruby-trace is mainly an easy way of adding debugging print statements that show the line number and filename, and that don't have to be removed when you're done with them.

On the other hand, people using Ruby-trace for larger systems, such as web servers, can use many features:

• They can give different subsystems their own independent tracing.

• Less frequent messages can be directed to a timestamped, fixed-size, versioned log file, while more detailed messages are stored in an internal ring buffer that's spilled to the logfile on error.

• The amount of detail recorded can be changed at runtime.

• Different subsystems can have their own logfiles, their own kinds of messages, and their own format for the output.

• And so forth.

The documentation is here.

Trace is distributed in two forms: as a zip file or a Unix-style tar file. Each contains the complete source (under a BSD-like license), the documentation, and tests. Unpack the archive, then begin by looking at the file "=README.txt".

The mailing list is at http://groups.yahoo.com/group/ruby-trace. You can subscribe by sending mail to ruby-trace-subscribe@yahoogroups.com.

Hope you like it.