carl::logging Namespace Reference

Contains a custom logging facility. More...

Data Structures
class	Filter
	This class checks if some log message shall be forwarded to some sink. More...
class	Formatter
	Formats a log messages. More...
class	Logger
	Main logger class. More...
struct	RecordInfo
	Additional information about a log message. More...
class	Sink
	Base class for a logging sink. More...
class	StreamSink
	Logging sink that wraps an arbitrary std::ostream. More...
class	FileSink
	Logging sink for file output. More...

Enumerations
enum class	LogLevel {   LVL_ALL , LVL_TRACE , LVL_DEBUG , LVL_INFO ,   LVL_WARN , LVL_ERROR , LVL_FATAL , LVL_OFF ,   LVL_DEFAULT = LVL_WARN }
	Indicated which log messages should be forwarded to some sink. More...

Functions
void	setInitialLogLevel ()
void	configureLogging ()
Logger &	logger ()
	Returns the single global instance of a Logger. More...
bool	visible (LogLevel level, const std::string &channel) noexcept
void	log (LogLevel level, const std::string &channel, const std::stringstream &ss, const RecordInfo &info)
std::ostream &	operator<< (std::ostream &os, LogLevel level)
	Streaming operator for LogLevel. More...

Detailed Description

Contains a custom logging facility.

This logging facility is fairly generic and is used as a simple and header-only alternative to more advanced solutions like log4cplus or boost::log.

The basic components are Sinks, Channels, Filters, RecordInfos, Formatters and the central Logger component.

A Sink represents a logging output like a terminal or a log file. This implementation provides a FileSink and a StreamSink, but the basic Sink class can be extended as necessary.

A Channel is a string that identifies the context of the log message, usually something like the class name where the log message is emitted. Channels are organized hierarchically where the levels are separated by dots. For example, carl is considered the parent of carl.core.

A Filter is associated with a Sink and makes sure that only a subset of all log messages is forwarded to the Sink. Filter rules are pairs of a Channel and a minimum LogLevel, meaning that messages of this Channel and at least the given LogLevel are forwarded. If a Filter does not contain any rule for some Channel, the parent Channel is considered. Each Filter contains a rule for the empty Channel, initialized with LVL_DEFAULT.

A RecordInfo stores auxiliary information of a log message like the filename, line number and function name where the log message was emitted.

A Formatter is associated with a Sink and produces the actual string that is sent to the Sink. Usually, it adds auxiliary information like the current time, LogLevel, Channel and information from a RecordInfo to the string logged by the user. The Formatter implements a reasonable default behaviour for log files, but it can be subclassed and modified as necessary.

The Logger class finally plugs all these components together. It allows to configure multiple Sink objects which are identified by strings called id and offers a central log() method.

Initial configuration may look like this:

carl::logging::logger().configure("logfile", "carl.log");
carl::logging::logger().filter("logfile")
    ("carl", carl::logging::LogLevel::LVL_INFO)
    ("carl.core", carl::logging::LogLevel::LVL_DEBUG)
;
carl::logging::logger().resetFormatter();

Macro facilitate the usage:

• CARLLOG_<LVL>(channel, msg) produces a normal log message where channel should be string identifying the channel and msg is the message to be logged.
• CARLLOG_FUNC(channel, args) produces a log message tailored for function calls. args should represent the function arguments.
• CARLLOG_ASSERT(channel, condition, msg) checks the condition and if it fails calls CARLLOG_FATAL(channel, msg) and asserts the condition.

Any message (msg or args) can be an arbitrary expression that one would stream to an std::ostream like stream << (msg);. No final newline is needed.

Enumeration Type Documentation

LogLevel

enum carl::logging::LogLevel

strong

Indicated which log messages should be forwarded to some sink.

All messages which have a level that is equal or greater than the specified value will be forwarded.

Enumerator
LVL_ALL	All log messages.
LVL_TRACE	Finer-grained informational events than the DEBUG.
LVL_DEBUG	Fine-grained informational events that are most useful to debug an application.
LVL_INFO	Highlight the progress of the application at coarse-grained level.
LVL_WARN	Potentially harmful situations or undesired states.
LVL_ERROR	Error events that might still allow the application to continue running.
LVL_FATAL	Severe error events that will presumably lead the application to terminate.
LVL_OFF	No messages.
LVL_DEFAULT	Default log level.

Definition at line 12 of file LogLevel.h.

Function Documentation

configureLogging()

void carl::logging::configureLogging ( )

inline

Definition at line 61 of file carl-logging.h.

Here is the call graph for this function:

Here is the caller graph for this function:

log()

void carl::logging::log	(	LogLevel	level,
		const std::string &	channel,
		const std::stringstream &	ss,
		const RecordInfo &	info
	)

Definition at line 11 of file logging.cpp.

Here is the call graph for this function:

logger()

Logger& carl::logging::logger ( )

inline

Returns the single global instance of a Logger.

Calls Logger::getInstance().

Returns

Logger object.

Definition at line 194 of file Logger.h.

Here is the call graph for this function:

Here is the caller graph for this function:

operator<<()

std::ostream& carl::logging::operator<< ( std::ostream &  os, LogLevel  level  )

inline

Streaming operator for LogLevel.

Parameters

os	Output stream.
level	LogLevel.

Returns

os.

Definition at line 39 of file LogLevel.h.

setInitialLogLevel()

void carl::logging::setInitialLogLevel

(

)

Definition at line 8 of file carl-logging.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

visible()

bool carl::logging::visible ( LogLevel  level, const std::string &  channel  )

noexcept

Definition at line 7 of file logging.cpp.

Here is the call graph for this function: