Unit-Trace

Unit-Trace is a library of tools for parsing, testing, and visualizing real-time scheduler traces. Unit-Trace is inspired by the philosophy of "unit testing", in which software is tested iteratively to ensure it behaves according to specification. Unit-Trace aims to help scheduler developers not only determine whether or not bugs exist, but to actually aid in debugging by providing detailed information about scheduler behavior.

About This Document

This document is both the offical Unit-Trace website and the complete Unit-Trace documentation.

Obtaining Unit-Trace

The latest public release of Unit-Trace (currently 2010.1) is available at:
http://cs.unc.edu/~mollison/unit-trace/unit-trace.tar.gz

Members of UNC's Real-Time Group should obtain Unit-Trace using:
git clone ssh://cvs.cs.unc.edu/cvs/proj/litmus/repo/unit-trace.git

Installing Unit-Trace

Dependencies: Python 2.6; for the visualizer, pygtk and pycairo.

Unit-Trace consists of a Python module called unit_trace (encapsulated in the unit_trace directory) and a font-end script called unit-trace.

You can use install.py to install Unit-Trace, or install manually by copying the unit-trace script and the unit_trace directory to ~/bin.

Make sure ~/bin is on your PATH.

Using Unit-Trace

Command line usage:
unit-trace <one or more trace files> [flags].

Each flag turns on or off a unit-trace submodule. The available submodules are given below.

You can specify module flags in any order.

For a quick usage reference (including a list of modules), type unit-trace on the command line, without any arguments.

Example Use Case

Let's assume you're in a directory with a bunch of trace files with the extension .bin. Each trace file is assumed to be the trace of a single CPU, and all trace files in the directory are from the same experimental run. (The sample_traces directory, included with Unit Trace, will work for this example.)

Suppose you want to get a list of the 10 longest priority inversions in a LITMUSRTtrace. Use the following command:
unit-trace *.bin -c -g -i 10.

Now, suppose you want to visualize one of those priority inversions. Given in the output for each one are the event IDs at the beginning and end of the priority inversion. Use the following command:
unit-trace *.bin -e <the first event ID> -l <the second event ID> -v.

Note that if the visualizer stops at the second specified event (which it will), any tasks running at that point will appear to keep running forever. If you specify a slightly later second event ID (e.g. 100 greater than the actual one), this won't affect the jobs you're actually interested in.

Now, suppose you want to see specific textual output for all events. (You could also specify a range if you wanted to.)
unit-trace *.bin -o > output

This example provides a basic overview of what you can do with Unit-Trace. Detailed information about all available submodules is provided in the next section.

List of Submodules

There are five basic kinds of submodules.

All submodules are listed and summarized in the tables below. Some submodules have further documentation, appearing later in this document.

Input Submodules

NameFlagParametersDescription
trace_parser always on, unless/until modules for other trace formats are contributed (None)Parses LITMUSRT traces

Filter Submodules

NameFlagParametersDescription
earliest-etimeFilters out records before the given event ID. (Event IDs are assigned in order of event record timestamp, and are displayed by the `stdio_printer` submodule.)
latest-ltimeFilters out records after the given event ID.
skipper-snumber nSkips the first n records
maxer-mnumber nAllows at most n records to be parsed
sanitizer-c(None)Modifies LITMUSRT traces. To be used in conjunction with the G-EDF tester. To summarize, LITMUSRT traces have some bogus records that need to be removed or altered in order for a (potentially) valid schedule to be represented.

Test Submodules

NameFlagOptionsDescription
gedf_test-g(None)Performs G-EDF testing.

Output Submodules

NameFlagOptionsDescription
stdout_printer-o(None)Prints records to standard out. You should probably redirect the output to a file when you use this.
visualizer-v(None)Visualizes records. You should probably use filters in conjunction with this submodule. Otherwise, it'll take forever to render, and do you really want to visualize the entire trace, anyway?
gedf_inversion_stat_printer-inumber nOutputs statistics about G-EDF inversions, and the n longest inversions. (You can specify n as 0 if you want.)

Miscellaneous Submodules

NameFlagOptionsDescription
progress-p(None)Outputs progress info (e.g number of records parsed so far, total time to process trace) to std error.

Specific Submodule Documentation

Here, documentation is provided for submodules for which relevant information is not considered to be self-evident.

(So far, it hasn't been necessary to add anything here, but once questions arise, it will become clear which submodules need to be documented more fully.)

Gotchas

Here, documentation is provided for potentially confusing topics that are not documented elsewhere.

A Note on Time

In general, Unit-Trace is agnostic about the units of time used in the trace files. This is not expected to change in the future. The exception is output modules. Currently, some output modules assume time is in nanoseconds; they convert it into milliseconds and print the 'ms' unit indicator, where convenient. This behavior may have to be modified in the future if non-nanosecond trace files are used.

Known Bugs

Here, documentation of known bugs is provided.

(No known bugs right now --- but there may be some hiding...)

Development

Please send patches to Mac Mollison or, if you are in the litmus group at UNC, just work with the git repo directly.

The following "rules" are currently in place:

Architecture

If you are interested in contributing to Unit-Trace, you probably ought to know a bit about its overall architecture.

Generally speaking, each Unit-Trace submodules is a Python generator. It accepts a Python iterator object as input and returns a Python iterator object as output. (You may want to look up the relevant Python terminology.)

The exceptions are input submodules, which do not take any input other than a list of trace files, and the output submodules, which do not return iterator objects.

The unit-trace script connects together the desired modules (i.e. those specified on the command line) using Python iterators.

This architecture provides two advantages. First, because Python iterators are evaluated lazily, it is not necessary to read an entire trace file into memory in order to run unit-trace on it. Second, it provides an easy-to-understand programming model.

Documentation

The source code for this page is included in the doc folder that comes with Unit-Trace. Contributors are required to make appropriate amendments to this documentation.

The source is stored in Markdown format in the file index.txt and can be built into HTML with make.

License

Unit-Trace is released under the Simplified BSD License.

Credits

This project was created by and is maintained by the Real-Time Systems Group at the University of North Carolina at Chapel Hill, Department of Computer Science. A detailed explanation of the tool is available in this paper, from the 2009 OSPERT workshop.

We would like to extend special thanks to Gary Bressler, who created and maintains the visualizer submodule as a volunteer with our group.

We hope to have additional contributors in the future.