fcppt.log

Description

Logging classes and functions.

Link to ${fcppt_log_TARGET}, or to fcppt_log_interface if you only need the headers.

Introduction A simple example Formatting and sinks Log hierarchy Log hierarchy design Log hierarchy example Thread safety Header files

Introduction

The following list highlights the main features of fcppt's logging library:

Configuration of enabled output:

The library assigns log levels to log locations, which is stored by a log context. Log levels are, for example, debug, warning, error and log locations are lists of strings.

Formatting and direction of messages:

A log context also assigns to each log level a level stream, which dictates where to log to, e.g. to std::clog, and how messages are formatted.

A simple example

The class that does actual logging is called fcppt::log::object. It refers to an fcppt::log::location in a fcppt::log::context. The following example illustrates the use of a simple log object:

  // Create a log context that has debug and every level above enabled
  fcppt::log::context context{
      fcppt::log::optional_level{fcppt::log::level::debug}, fcppt::log::default_level_streams()};
 
  // Create a log object at location "{ fcppt }"
  fcppt::log::object const log{fcppt::make_ref(context), fcppt::log::name{FCPPT_TEXT("fcppt")}};
 
  // Outputs "fcppt: debug: Hello World"
  if (log.enabled(fcppt::log::level::debug))
  {
    log.log(fcppt::log::level::debug, fcppt::log::out << FCPPT_TEXT("Hello World"));
  }
 
  // The same as above using a shorthand macro
  FCPPT_LOG_DEBUG(log, fcppt::log::out << FCPPT_TEXT("Hello World"))
 
  // This is not printed because the verbose level is not enabled
  FCPPT_LOG_VERBOSE(log, fcppt::log::out << FCPPT_TEXT("Very verbose message"))

Logging is done via the fcppt::log::object::log element function. The macro FCPPT_LOG_DEBUG is a short-hand for logging only if the debug log level is enabled. This is important because the construction of the log message is avoided altogether when debug is not enabled.

fcppt::log::out is an object that basically acts like a std::basic_ostream. This is used to create a whole message in a thread-safe manner. If you log in multiple pieces instead, the log message might end up interleaved with other messages.

Formatting and sinks

A log context contains an fcppt::log::level_stream for every log level. Each of them controls where output is written to and how it is formatted.

Log hierarchy

Controlling at runtime which messages are logged is very important. Under normal circumstances, you probably want to only log serious problems, while in a debug scenario a lot of debug messages should be logged.

Log hierarchy design

A location is a list of fcppt::log::name values, e.g. {"my_lib", "my_subsystem"}. An fcppt::log::context associates locations with fcppt::log::optional_level values. These can be configured through the fcppt::log::context::set function, even before any log objects are created. This is useful, for example, for specifying log levels on the command line.

Each log object refers to a location of a given context. In its constructor, it gets a name, and in addition to that, it gets either

• a log context, in which case its location is its name,
• a log context and a location, in which case its location is the given location plus its name, or
• a parent log object, in which case its location is the parent's location plus its own name.

Log hierarchy example

The next example shows how log objects, contexts and locations can be used together.

The log context gets a single fcppt::log::optional_level as its parameter, which is used as a default for every location, unless changed.

  fcppt::log::context context{
      fcppt::log::optional_level{fcppt::log::level::debug}, fcppt::log::default_level_streams()};

We declare a root object with name "root". Its location will be {"root"}.

  fcppt::log::name const root_name{FCPPT_TEXT("root")};
 
  fcppt::log::object const root_log{fcppt::make_ref(context), root_name};

The child object gets the name "child" and the root object passed to its constructor, thus its location is {"root", "child"}.

  fcppt::log::name const child_name{FCPPT_TEXT("child")};
 
  fcppt::log::object const child_log{root_log, child_name};

As mentioned earlier, the locations inherit the root level of the context, so every log object currently has the debug level and all levels above enabled: The log location given to a log object implicitly changes how its output is formatted:

  FCPPT_LOG_INFO(root_log, fcppt::log::out << FCPPT_TEXT("Print from root!"))
 
  FCPPT_LOG_INFO(child_log, fcppt::log::out << FCPPT_TEXT("Print from child!"))

The first statement will print root: warning: Print from root. and the second statement will print root: child: warning: Print from child.

The fcppt::log::context::set function can be used to change the level of a location at runtime.

  context.set(
      fcppt::log::location{root_name} / child_name,
      fcppt::log::optional_level{fcppt::log::level::warning});

Here we change the child location to only have the warning level and every level above enabled, so the following output is not printed:

  FCPPT_LOG_INFO(child_log, fcppt::log::out << FCPPT_TEXT("shouldn't be shown!"))

Note that changing the level at a location also changes the levels below it. We can change the root level back to debug which will also affect the child level:

  context.set(
      fcppt::log::location{root_name}, fcppt::log::optional_level{fcppt::log::level::debug});
 
  FCPPT_LOG_INFO(child_log, fcppt::log::out << FCPPT_TEXT("This is now shown!"))

Passing an empty optional log level disables all levels.

Thread safety

The log context contains a mutex to protect its internal structure from race conditions. Therefore, calling element functions of a log context from multiple threads is safe. Log objects can be used in different threads than the log context. However, sharing a log object between different threads is not safe.

Header files

All headers are relative to the log subdirectory.

Essential header files

Header file	Description
out.hpp	Contains fcppt::log::out .
context_fwd.hpp	Contains fcppt::log::context 's declaration.
context.hpp	Contains fcppt::log::context 's definition.
debug.hpp	Contains the FCPPT_LOG_DEBUG macro.
error.hpp	Contains the FCPPT_LOG_ERROR macro.
fatal.hpp	Contains the FCPPT_LOG_FATAL macro.
info.hpp	Contains the FCPPT_LOG_INFO macro.
level.hpp	Contains the fcppt::log::level enumeration.
location_fwd.hpp	Contains fcppt::log::location 's declaration.
location.hpp	Contains fcppt::log::location 's definition.
name_fwd.hpp	Contains fcppt::log::name's declaration.
name.hpp	Contains fcppt::log::name's definition.
object_fwd.hpp	Contains fcppt::log::object 's declaration.
object.hpp	Contains fcppt::log::object 's defintiion.
verbose.hpp	Contains the FCPPT_LOG_VERBOSE macro.
warning.hpp	Contains the FCPPT_LOG_WARNING macro.

Other header files

Header file	Description
default_level_streams.hpp	Contains fcppt::log::default_level_streams for construction of all level stream defaults.
default_stream.hpp	Contains the fcppt::log::default_stream function.
level_from_string.hpp	Contains fcppt::log::level_from_string .
level_stream_array.hpp	Contains the fcppt::log::level_stream_array typedef.
level_stream_fwd.hpp	Contains fcppt::log::level_stream 's declaration.
level_stream.hpp	Contains fcppt::log::level_stream 's definition.
level_to_string.hpp	Contains fcppt::log::level_to_string .
optional_level_fwd.hpp	Contains the fcppt::log::optional_level typedef.
optional_level.hpp	Includes optional_level_fwd.hpp and optional headers.

Classes
class	fcppt::log::context
	A logger context manages log levels. More...
class	fcppt::log::level_stream
	The stream for a logger level. More...
class	fcppt::log::location
	A location of a logger in a context. More...
class	fcppt::log::object
	The main log class. More...
class	fcppt::log::standard_level_stream
	Logs to an fcppt::io::ostream. More...

Macros
#define	FCPPT_LOG_DEBUG(stream, output)
	Log to a stream if its debug level is enabled.
#define	FCPPT_LOG_ERROR(stream, output)
	Log to a stream if its error level is enabled.
#define	FCPPT_LOG_FATAL(stream, output)
	Log to a stream if its fatal level is enabled.
#define	FCPPT_LOG_INFO(stream, output)
	Log to a stream if its info level is enabled.
#define	FCPPT_LOG_VERBOSE(stream, output)
	Log to a stream if its verbose level is enabled.
#define	FCPPT_LOG_WARNING(stream, output)
	Log to a stream if its warning level is enabled.

Typedefs
using	fcppt::log::level_stream_array
	An array used to save log level streams for every level.
using	fcppt::log::location_string_vector = std::vector<fcppt::string>
using	fcppt::log::name = fcppt::strong_typedef< fcppt::string ,_>
	The name of a logger.
using	fcppt::log::optional_level = fcppt::optional::object<fcppt::log::level>
	An optional level.
using	fcppt::log::standard_level_stream_array
	The array of standard level streams.

Enumerations
enum class	fcppt::log::level : std::uint8_t {   fcppt::log::level::verbose , fcppt::log::level::debug , fcppt::log::level::info , fcppt::log::level::warning ,   fcppt::log::level::error , fcppt::log::level::fatal }
	An enumeration for the available log levels. More...

Functions
FCPPT_LOG_DETAIL_SYMBOL fcppt::log::level_stream_array	fcppt::log::default_level_streams ()
	Constructs the default level streams.
FCPPT_LOG_DETAIL_SYMBOL fcppt::log::optional_level	fcppt::log::level_from_string (fcppt::string_view name)
	Converts the name of a log level to its enum.
FCPPT_LOG_DETAIL_SYMBOL fcppt::io::istream &	fcppt::log::operator>> (fcppt::io::istream &, fcppt::log::level &)
	Reads a level from a stream.
FCPPT_LOG_DETAIL_SYMBOL fcppt::io::ostream &	fcppt::log::operator<< (fcppt::io::ostream &, fcppt::log::level)
	Outputs a level to a stream.
FCPPT_LOG_DETAIL_SYMBOL std::string_view	fcppt::log::level_to_string (fcppt::log::level)
	Converts a log level to its string representation.

Variables
FCPPT_LOG_DETAIL_SYMBOL fcppt::log::detail::output_helper const	fcppt::log::out
	Trampoline to create logger output.

Macro Definition Documentation

FCPPT_LOG_DEBUG

#define FCPPT_LOG_DEBUG	(		stream,
			output )

Value:

  FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::debug, output)

Log to a stream if its debug level is enabled.

FCPPT_LOG_ERROR

#define FCPPT_LOG_ERROR	(		stream,
			output )

Value:

  FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::error, output)

Log to a stream if its error level is enabled.

FCPPT_LOG_FATAL

#define FCPPT_LOG_FATAL	(		stream,
			output )

Value:

  FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::fatal, output)

Log to a stream if its fatal level is enabled.

FCPPT_LOG_INFO

#define FCPPT_LOG_INFO	(		stream,
			output )

Value:

  FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::info, output)

Log to a stream if its info level is enabled.

FCPPT_LOG_VERBOSE

#define FCPPT_LOG_VERBOSE	(		stream,
			output )

Value:

  FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::verbose, output)

Log to a stream if its verbose level is enabled.

FCPPT_LOG_WARNING

#define FCPPT_LOG_WARNING	(		stream,
			output )

Value:

  FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::warning, output)

Log to a stream if its warning level is enabled.

Typedef Documentation

level_stream_array

using fcppt::log::level_stream_array

Initial value:

 
    fcppt::enum_::array<fcppt::log::level, fcppt::unique_ptr<fcppt::log::level_stream>>

An array used to save log level streams for every level.

An array of fcppt::log::level_stream with the size fcppt::log::level. Each entry corresponds to an enumerator from fcppt::log::level.

location_string_vector

using fcppt::log::location_string_vector = std::vector<fcppt::string>

name

using fcppt::log::name = fcppt::strong_typedef< fcppt::string ,_>

The name of a logger.

optional_level

using fcppt::log::optional_level = fcppt::optional::object<fcppt::log::level>

An optional level.

standard_level_stream_array

using fcppt::log::standard_level_stream_array

Initial value:

 
    fcppt::enum_::array<fcppt::log::level, fcppt::unique_ptr<fcppt::log::standard_level_stream>>

The array of standard level streams.

Enumeration Type Documentation

level

enum class fcppt::log::level : std::uint8_t

strong

An enumeration for the available log levels.

Every enumerator state here represents a less serious log level than the next one. For example, info is less serious than warning. size itself is not a valid log level.

Enumerator
verbose	Used for verbose messages. Verbose is the lowest log level, and so it should be used without any reserve.
debug	Used for debug messages. The debug log level should be used whenever information is required that is only useful during debugging and would be too verbose otherwise.
info	Used for info messages. The info log level should be used whenever information is required that is not too verbose. It is a good candidate to activate as default log level.
warning	Used for warning messages. The warning log level should be used whenever something must be printed that is important for the user to read, but most of the time doesn't lead to any errors. It is not recommended to turn this off.
error	Used for error messages. The error log level should be used whenever an error occurs, but it is still possible for the system to handle the situation. It is not recommended to turn this off.
fatal	Used for fatal messages. The fatal log level should be used whenever an error occurs that cannot be handled.

Function Documentation

default_level_streams()

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::level_stream_array fcppt::log::default_level_streams

(

)

Constructs the default level streams.

Each level stream uses fcppt::log::standard_level_stream.

level_from_string()

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::optional_level fcppt::log::level_from_string

(

fcppt::string_view

name

)

Converts the name of a log level to its enum.

Converts the name of a log level given by name to its corresponding level enumerator. Accepts all strings as parameters that are listed in fcppt::log::level.

Parameters

name	the name of the log level

level_to_string()

FCPPT_LOG_DETAIL_SYMBOL std::string_view fcppt::log::level_to_string

(

fcppt::log::level

)

Converts a log level to its string representation.

Converts a log level given by level to its enumerator name as a string.

operator<<()

FCPPT_LOG_DETAIL_SYMBOL fcppt::io::ostream & fcppt::log::operator<<	(	fcppt::io::ostream &	,
		fcppt::log::level	)

Outputs a level to a stream.

operator>>()

FCPPT_LOG_DETAIL_SYMBOL fcppt::io::istream & fcppt::log::operator>>	(	fcppt::io::istream &	,
		fcppt::log::level &	)

Reads a level from a stream.

Variable Documentation

out

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::detail::output_helper const fcppt::log::out

extern

Trampoline to create logger output.

Use this object to output to a log stream.