Logger

Summary of logging features.

API

The core API is in logger/log.hpp, which contains free functions to error, warning, info, and debug log messages. General usage involves including this header and calling the relevant log functions. All functions can be called from any thread at any time.

Instance

The internals of the logger are controlled by an RAII logger::Instance that the user is expected to own for as long as they need logging (in most cases at the top of main). Its constructor takes a path to create a log file at, and the log configuration to use (described below). It also allows overwriting the configuration at runtime, and adding custom sinks.

Target

A logger::Target describes the "channels" to route logs through:

1. console_v: stdout / stderr.
2. file_v: to the log file created by Instance.
3. sinks_v: to custom sinks connected (if any).
4. all_v: everything.

Config

logger::Config exposes various knobs and switches:

1. format: A format string providing the layout of formatted log messages.
2. maxLevel: Maximum Level to log.
3. categoryMaxLevels: Maximum Level override per category (by default the same as maxLevel).
4. levelTargets: destinations for each Level (by default all).
5. timestamp: whether to print local / UTC timestamps.

Since the logging API is thread-safe, there is no way to obtain a reference to the currently active Config, it can be only be copied and swapped.

Sink

logger::Sink is a customization point for receiving formatted log messages. Inherit from it, override handle(std::string_view formatted, Context const& context), and add an instance of your type via Instance::addSink, to receive callbacks on every logged message.

Context

logger::Context contains all the relevant metadata for a particular log message, passed in Sink callbacks. It can be useful to mirror log messages on a Dear ImGui window, for example.