schnorr / librastro

librastro is a generic tracing library to register the behavior of any computer program

librastro

librastro is a generic tracing library to register the behavior of any computer program. It is especially tailored for parallel or distributed applications, providing a low memory footprint and low intrusion. The library is flexible, enabling the definition of events with application-dependent information, and offers a clock synchronization tool based on a linear regression to synchronize timestamps registered on different computers.

Application Instrumentation

The application to be traced must be instrumented with functions that start with rst_event_. All events are timestamped according to the local timestamp of the machine in the moment the tracing function is executed. New functions can be created arbitrary by a rastro_generate (see below for additional information, or rastro_generate --help), so the user is not limited by existing functions. A rst_event_ function is on the following form:

rst_event_X where a X can be one or a combination of:

  c - 8 bits
  w - 16 bits
  i - 32 bits
  l - 64 bits
  f - float
  d - double
  s - string

The size of each event is unlimited (actually, hard-coded to 1000 bytes, but you can change that if you need even bigger events), so users can provide as many parameters as desired. Examples:

  rst_event_iicilf(...)
  rst_event_siicicffll(...)

Instrumentation Functions Generation

librastro has a program to automatically implement functions defined by the user and that are not present in the library. The user is encouraged to launch the program with the help parameter to obtain more information:

 $ rastro_generate --help

One possible way to pass the functions to be implemented to rastro_generate is to create a textual file with one combination of X (as described above) per line, like this:

 $ cat used_functions.txt
 ii
 fl
 ds

Then, the user can call rastro_generate passing the -i parameter and the corresponding file:

 $ rastro_generate -h code.h -c code.c -i used_functions.txt

Compiling generated functions and librastro linking

The user has to add to the compilation chain the files created by rastro_generate. Then, link the final binary to the librastro library using -lrastro as parameter to the linker.