tempest/resources/3rdparty/l3pp

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

Concepts

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.

Log levels

The following log levels exist (from l3pp::LogLevel):

• ALL
• TRACE
• DEBUG
• INFO
• WARN
• ERR
• FATAL
• OFF

Hierarchical Loggers

Loggers are hierarchically structured strings like "app.module.submodule". In this example, submodule is considered a sublogger of module and 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 l3pp::Logging::getRootLogger().

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 Logger::setAdditive(false)).

Sinks

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.

Formatters

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 l3pp::makeTemplateFormatter.

Basic Usage

A logger object can be accessed via l3pp::Logger::getLogger() or 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

Considerations

Performance

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 L3PP_LOG_* macros. 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_LOGGING macro, prefix your macros with your project name. Otherwise, these macros will collide.

Implementation Details

Sinks

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 std::cout.

Formatters

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 FieldStr and TimeStr can be used to format particular attributes of a log entry.