Clutchlog is a logging system which targets versatile debugging. It allows to (de)clutch messages for a given: log level, source code location or call stack depth.
-Clutchlog allows to select which log messages will be displayed, based on their locations:
Additionally, Clutchlog will do its best to allow the compiler to optimize out calls, for instance debug messages in "Release" builds.
-Adding a message is a simple as calling a macro (which is declutched in Debug build type, when NDEBUG is not defined):
To configure the display, you indicate the three types of locations, for example in your main function:
For more detailled examples, see the "API documentation" section below and the tests directory.
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 (typically 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.
-The main entrypoint is the CLUTCHLOG macro, which takes the desired log level and message. The message can be anything which can be output in an ostringstream.
There is also a macro to dump the content of an iterable within a separate file: CLUTCHDUMP. This function takes care of incrementing a numeric suffix in the file name, if an existing file with this name exists.
Note that if you pass a file name without the {n} tag, the file will be overwritten as is.
To configure the global behaviour of the logger, you must first get a reference on its (singleton) instance:
One can configure the location(s) at which messages should actually be logged:
Current levels are defined in an enumeration as clutchlog::level:
File, function and line filters are indicated using (ECMAScript) regular expressions:
A shortcut function can be used to filter all at once:
Strings may be used to set up the threshold, using level_of:
Note that the case of the log levels strings matters (see below).
-The output stream can be configured using the out method:
The format of the messages can be defined with the format method, passing a string with standardized tags surrounded by {}:
Available tags are:
{msg}: the logged message,The default log format is "[{name}] {level_letter}:{depth_marks} {msg}\t\t\t\t\t{func} @ {file}:{line}\n", it can be overriden at compile time by defining the CLUTCHLOG_DEFAULT_FORMAT macro.
The default format of the comment added with the dump macro is "# [{name}] {level} in {func} (at depth {depth}) @ {file}:{line}". It can be edited with the format_comment method. If it is set to an empty string, then no comment line is added. The default can be modified at compile time with CLUTCHDUMP_DEFAULT_FORMAT. By default, the separator between items in the container is a new line. To change this behaviour, you can change CLUTCHDUMP_DEFAULT_SEP or call the low-level dump method.
The mark used with the {depth_marks} tag can be configured with the depth_mark method, and its default with the CLUTCHLOG_DEFAULT_DEPTH_MARK macro:
The mark used with the {depth_marks} tag can be configured with the depth_mark method, and its default with the CLUTCHLOG_DEFAULT_DEPTH_MARK macro:
The output can be colored differently depending on the log level.
Or, if you want to declare some semantics beforehand:
Using the clutchlog::fmt class, you can style:
clutchlog::fmt::fg,You may use styling within the format message template itself, to add even more colors:
Note: messages at the "critical", "error" and "warning" log levels are colored by default. You may want to set their style to none if you want to stay in control of inserted colors in the format template.
By default, clutchlog is always enabled if the NDEBUG preprocessor variable is not defined (this variable is set by CMake in build types that differs from Debug).
You can however force clutchlog to be enabled in any build type by setting the WITH_CLUTCHLOG preprocessor variable.
When the NDEBUG preprocessor variable is set (e.g. in Release build), clutchlog will do its best to allow the compiler to optimize out any calls for log levels which are under or equal to progress.
You can change this behavior at compile time by setting the CLUTCHLOG_DEFAULT_DEPTH_BUILT_NODEBUG preprocessor variable to the desired maximum log level, for example:
Note that allowing a log level does not mean that it will actually output something. If the configured log level at runtime is lower than the log level of the message, it will still not be printed.
This behavior intend to remove as many conditional statements as possible when not debugging, without having to use preprocessor guards around calls to clutchlog, thus saving run time at no readability cost.
-All configuration setters have a getters counterpart, with the same name but taking no parameter, for example:
To control more precisely the logging, one can use the low-level log method:
A helper macro can helps to fill in the location with the actual one, as seen by the compiler:
A similar dump method exists:
All configuration setters have a getters counterpart, with the same name but taking no parameter, for example:
To control more precisely the logging, one can use the low-level log method:
A helper macro can helps to fill in the location with the actual one, as seen by the compiler:
A similar dump method exists:
Log levels use a classical semantics for a human skilled in the art, in decreasing order of importance:
Note: the log levels constants are lower case (for example: clutchlog::level:xdebug), but their string representation is not (e.g. "XDebug", this should be taken into account when using level_of).
Because the call stack depth and program name access are system-dependent, the features relying on the depth of the call stack and the display of the program name are only available for operating systems having the following headers: execinfo.h, stdlib.h and libgen.h (so far, tested with Linux).
Some colors/styles may not be supported by some exotic terminal emulators.
Clutchlog needs C++-17 with the filesystem feature. You may need to indicate -std=c++17 -lstdc++fs to your compiler.
To use clutchlog, just include its header in your code and either ensure that the NDEBUG preprocessor variable is not set, either define the WITH_CLUTCHLOG preprocessor variable.
If you're using CMake (or another modern build system), it will unset NDEBUG —and thus enable clutchlog— only for the "Debug" build type, which is usually what you want if you use clutchlog, anyway.
To build and run the tests, just use a classical CMake workflow:
There's a script which tests all the build types combinations: ./build_all.sh.