Clutchlog is a logging system whith targets versatile debugging. It allows to (de)clutch messages either for a given: log level, source code location or call stack depth.

Features

Clutchlog allows to select which log messages will be displayed, based on their locations:

• classical log levels: each message has a given detail level and it is displayed if you ask for a at least the same one (current ones: quiet, error, warning, info, debug, xdebug).
• call stack depth: you can ask to display messages within functions which are called up to a given stack depth.
• source code location: you can ask to display messages called from given files, functions and line number, all based on regular expressions.

Appart from those, Clutchlog have classical logging system features: output selection, default to unbuffered mode, etc.

Of course, Clutchlog is disabled by default if NDEBUG is not defined.

Example

Adding a message is a simple as calling a macro (which is declutched in Debug build type):

CLUTCHLOG(info, "matrix size: " << m << "x" << n);

To configure the display, you indicate the three types of locations, for example in your main function:

    auto& log = clutchlog::logger();
    log.depth(2);                          // Log functions called from "main" but not below.
    log.threshold(clutchlog::level::info); // Log "info", "warning", "error" or "quiet" messages.
    log.file("algebra/.*");                // Will match any file in the "algebra" directory.
    log.func("(mul|add|sub|div)");         // Will match "multiply", for instance.

For more detailled examples, see the tests directory.

Rationale

Most of existing logging systems targets service events storage, like fast queuing of transactions in a round-robin database. Their aim is to provide a simple interface to efficiently store messages somewhere, which is appropriated when you have a well known service running and you want to be able to trace complex users interactions across its states.

Clutchlog, however, targets the debugging of a (single-run) program. While you develop your software, it's common practice to output several detailled informations on the internal states around the feature you are currently programming. However, once the feature is up and running, those detailled informations are only useful if you encounter a bug traversing this specific part.

While tracing a bug, it is tedious to uncomment old debugging code (and go on the build-test cycle) or to set up a full debugger session which displays all appropriate data (with ad-hoc fancy hooks).

To solve this problem, Clutchlog allows to disengage your debug log messages in various parts of the program, allowing for the fast tracking of a bug across the execution.

Limitations

Call stack depth is only implemented for Linux.

Build and tests

To build and run the tests, just use a classical CMake workflow:

mkdir build
cd build
cmake ..
make
ctest