L3++: Lightweight Logging Library for C++
L3++ is a self-contained, single-header, cross-platform logging library for C++.
The main goals for this library are simplicity, modularity and ease of use. This library is released under the MIT License.
Copyright (C) 2015 Gereon Kremer
L3++ is based on the following conceptual components:
- RecordInfo: A record info stores auxiliary information of a log message like the filename, line number and function name where the log message was emitted.
- Logger: A logger categorizes log messages, usually according to logical components or modules in the source code.
- Sink: A sink represents a logging output, for example the terminal or a log file.
- Formatter: A formatter is associated with a sink and converts a log message into an actual string.
The following log levels exist (from
Loggers are hierarchically structured strings like
"app.module.submodule". In this example,
submodule is considered a sublogger of
app the parent of
module. A sublogger implicitly inherits all sinks and the log level of the parent, unless explicitly configured otherwise.
The hierarchical tree of loggers always contains the root logger at the top. The root logger itself does not have a parent, nor a name. It can be accessed via
Each logger is assigned a log level, or is configured to inherit the log level of the parent (with the special log level
l3pp::LogLevel::INHERIT). Note that the root logger cannot inherit a log level. Any log entry with a lower level is filtered out and will not be logged.
A logger can also be assigned one or more sinks. By default, a logger will log to both the sinks of its parent, as well as its own sinks. Should a logger only use it own sinks, it should be set to non-additive (using
A sink provides an output for loggers. Loggers may define multiple sinks, and sinks may be shared between loggers. Sinks are associated with a formatter and a log level. The log level specifies the minimum level of a message for it to be output (independent of the log level of a logger), and by default permits all log messages. A formatter formats the log messages before being output. By default, a simple formatter is used which prints the log level, message and a newline, but other formatters can be specified.
A formatter shapes a log message before being sent to its final destination. A non-configurable simple formatter exists, as well as a template-based formatter. The latter specifies the format of a message by means of its template arguments, see
A logger object can be accessed via
l3pp::Logger::getRootLogger(). By default, the root logger does not output anywhere. Therefore, a sink should be added. An initial configuration may look like this:
l3pp::Logger::initialize(); l3pp::SinkPtr sink = log4carl::StreamSink::create(std::clog); l3pp::Logger::getRootLogger()->addSink(sink); l3pp::Logger::getRootLogger()->setLevel(log4carl::LogLevel::INFO);
In this demo, a single sink is created that passes log messages to the standard logging stream
std::clog. All messages must have at least level
LVL_INFO before being printed.
The actual logging is performed using a handful of macros. These macros
While the use of hierarchical loggers and multiple sinks with associated formatters gives a lot of flexibility, it comes at a certain price. As the configuration is done at runtime (and may even change at runtime), the question whether a certain message is printed can only be answered at runtime. Therefore, every message, whether you will ever see it or not, has to pass through the logger and cost runtime.
To mitigate this, we suggest the following:
Create a preprocessor flag (like
ENABLE_LOGGING) and define your own set of logging macros.
If this flag is defined, make your macros forward to the
If this flag is not defined, make your macros do nothing.
Multiple usages in the same project
Assume you have an application that uses L3++ for logging as well as some other library that also uses L3++. L3++ will play nicely in this scenario (partly, it was designed for this case).
However, you should take care of a few things:
- Colliding loggers: Prefix your loggers with some unique prefix.
- Colliding macros: If you implement the aforementioned
ENABLE_LOGGINGmacro, prefix your macros with your project name. Otherwise, these macros will collide.
A sink is a class that provides some
log method. Any class that inherits from
l3pp::Sink can be used.
As of now, two implementations are available:
- FileSink: Writes to a output file.
- StreamSink: Writes to any given
std::ostream, for example to
A formatter is a functor that given a log entry, provides a formatted string. The base class
Formatter provides some very simple formatting, whereas
TemplateFormatter provides more control over the shape. Internally, a
TemplateFormatter streams its arguments to a stream before constructing the string. The special types
TimeStr can be used to format particular attributes of a log entry.