A library for working with phylogenetic and population genetic data.
v0.27.0
Logging Class Reference

#include <genesis/utils/core/logging.hpp>

Detailed Description

Logging class with easy and fast usage.

The basic usage of this class is to invoke the macros for the different types of log messages and send a stream of messages to them:

LOG_DBG << "you are here";
LOG_ERR << "there was an error: " << 42;

The provided types of macros are: LOG_ERR, LOG_WARN, LOG_INFO, LOG_DBG, LOG_DBG1, LOG_DBG2, LOG_DBG3, LOG_DBG4 for all levels of logging explained in LoggingLevel.

The details that are logged with each message can be changed via accessing Logging::details – see LoggingDetails for more on that.

In order to use this class, at least one output stream has to be added first by invoking either AddOutputStream or AddOutputFile.

The depths of logging can be changed in order to reduce the amount of written messages. First, at compile time the macro constant LOG_LEVEL_MAX can be set (e.g. in the Makefile) to the highest level that shall be logged. All log invoakations with a higher level are never called, and moreover will be pruned from the code by most compilers completetly. This makes the log class fast – instead of deleting all log invokations by hand, it is sufficient to set the constant to a low level. Second, the depths of logging can be changed dynamically at run time by setting Logging::max_level to the desired value. Of course, this value cannot be higher than LOG_LEVEL_MAX, because those logs are already pruned by the compiler.

There are also three more special log types that create a different output than the previously mentioned types: LOG_BOLD, LOG_TIME and LOG_PROG. See their respective documentation for more information.

The inner working of this class is as follows: Upon invokation via one of the macros, an instance is created that stays alive only for the rest of the source code line. In this line, the log message is inserted to the buffer stream. After the line finishes, the object is automatically destroyed, so that its destructor is called. In the destructor, the message is composed and logged to all given output streams.

Caveat: Because the macro contains conditions depending on the log level, do not use code in a log line that changes the program state. Therefore, instead of

LOG_INFO << "this is iteration " << ++i;

use

++i;
LOG_INFO << "this is iteration " << i;

because the former will not work when the max log level is below info level.

Definition at line 386 of file logging.hpp.

Public Member Functions

 Logging ()
 
 Logging (const Logging &)
 
 ~Logging ()
 Destructor that is invoked at the end of each log line and does the actual output. More...
 
std::ostringstream & get (const std::string &file, const int line, const std::string &function, const LoggingLevel level)
 Getter for the singleton instance of log, is called by the standard macros. More...
 
std::ostringstream & get (const std::string &file, const int line, const std::string &function, const LoggingLevel level, const LoggingDetails dets)
 Getter for the singleton instance of log, is called by special macros that change the details of the log message. More...
 
Loggingoperator= (const Logging &)=delete
 

Static Public Member Functions

static void clear ()
 Remove all output streams, so that nothing is logged any more. More...
 
static std::string level_to_string (const LoggingLevel level)
 Return a string representation of a log level. More...
 
static void log_debug (const std::string &msg)
 
static void log_debug_1 (const std::string &msg)
 
static void log_debug_2 (const std::string &msg)
 
static void log_debug_3 (const std::string &msg)
 
static void log_debug_4 (const std::string &msg)
 
static void log_error (const std::string &msg)
 
static void log_info (const std::string &msg)
 
static void log_message (const std::string &msg)
 
static void log_message_1 (const std::string &msg)
 
static void log_message_2 (const std::string &msg)
 
static void log_message_3 (const std::string &msg)
 
static void log_message_4 (const std::string &msg)
 
static void log_to_file (const std::string &fn)
 Add an output file to which log messages are written. More...
 
static void log_to_stdout ()
 Add stdout as output stream to which log messages are written. More...
 
static void log_to_stream (std::ostream &os)
 Add an output stream to which log messages are written. More...
 
static void log_warning (const std::string &msg)
 
static LoggingLevel max_level ()
 Get the highest log level that is reported. More...
 
static void max_level (const LoggingLevel level)
 Set the highest log level that is reported. More...
 
static int report_percentage ()
 Get the current percentage for reporting LOG_PROG messages. More...
 
static void report_percentage (const int percentage)
 set the percentage for reporting LOG_PROG messages. More...
 

Public Types

enum  LoggingLevel {
  kNone = 0, kError, kWarning, kInfo,
  kProgress, kMessage, kMessage1, kMessage2,
  kMessage3, kMessage4, kDebug, kDebug1,
  kDebug2, kDebug3, kDebug4
}
 Levels of severity used for logging. More...
 

Static Public Attributes

static std::string debug_indent = " "
 Indention string for Debug Levels 1-4. More...
 
static LoggingDetails details
 Settings for which information is included with each log message. See LoggingDetails for usage. More...
 

Protected Attributes

std::ostringstream buff_
 
LoggingDetails details_ = {}
 
std::string file_
 
std::string function_
 
LoggingLevel level_ = {}
 
int line_ = 0
 

Static Protected Attributes

static long count_ = 0
 
static std::vector< std::unique_ptr< std::ofstream > > fstreams_
 
static clock_t last_clock_ = 0
 
static LoggingLevel max_level_ = kDebug4
 
static std::vector< std::ostream * > ostreams_
 
static int report_percentage_ = 5
 

Constructor & Destructor Documentation

◆ Logging() [1/2]

Logging ( )
inline

Definition at line 452 of file logging.hpp.

◆ ~Logging()

~Logging ( )

Destructor that is invoked at the end of each log line and does the actual output.

Definition at line 184 of file logging.cpp.

◆ Logging() [2/2]

Logging ( const Logging )
inline

Definition at line 458 of file logging.hpp.

Member Function Documentation

◆ clear()

void clear ( )
static

Remove all output streams, so that nothing is logged any more.

Definition at line 170 of file logging.cpp.

◆ get() [1/2]

std::ostringstream & get ( const std::string &  file,
const int  line,
const std::string &  function,
const LoggingLevel  level 
)

Getter for the singleton instance of log, is called by the standard macros.

It returns the string stream buffer used to capture the log messages.

Definition at line 279 of file logging.cpp.

◆ get() [2/2]

std::ostringstream & get ( const std::string &  file,
const int  line,
const std::string &  function,
const LoggingLevel  level,
const LoggingDetails  dets 
)

Getter for the singleton instance of log, is called by special macros that change the details of the log message.

It stores some relevant information and returns the string stream buffer used to capture the log messages.

Definition at line 294 of file logging.cpp.

◆ level_to_string()

std::string level_to_string ( const LoggingLevel  level)
static

Return a string representation of a log level.

Definition at line 116 of file logging.cpp.

◆ log_debug()

static void log_debug ( const std::string &  msg)
inlinestatic

Definition at line 554 of file logging.hpp.

◆ log_debug_1()

static void log_debug_1 ( const std::string &  msg)
inlinestatic

Definition at line 559 of file logging.hpp.

◆ log_debug_2()

static void log_debug_2 ( const std::string &  msg)
inlinestatic

Definition at line 564 of file logging.hpp.

◆ log_debug_3()

static void log_debug_3 ( const std::string &  msg)
inlinestatic

Definition at line 569 of file logging.hpp.

◆ log_debug_4()

static void log_debug_4 ( const std::string &  msg)
inlinestatic

Definition at line 574 of file logging.hpp.

◆ log_error()

static void log_error ( const std::string &  msg)
inlinestatic

Definition at line 514 of file logging.hpp.

◆ log_info()

static void log_info ( const std::string &  msg)
inlinestatic

Definition at line 524 of file logging.hpp.

◆ log_message()

static void log_message ( const std::string &  msg)
inlinestatic

Definition at line 529 of file logging.hpp.

◆ log_message_1()

static void log_message_1 ( const std::string &  msg)
inlinestatic

Definition at line 534 of file logging.hpp.

◆ log_message_2()

static void log_message_2 ( const std::string &  msg)
inlinestatic

Definition at line 539 of file logging.hpp.

◆ log_message_3()

static void log_message_3 ( const std::string &  msg)
inlinestatic

Definition at line 544 of file logging.hpp.

◆ log_message_4()

static void log_message_4 ( const std::string &  msg)
inlinestatic

Definition at line 549 of file logging.hpp.

◆ log_to_file()

void log_to_file ( const std::string &  fn)
static

Add an output file to which log messages are written.

This creates a stream to the file.

Definition at line 155 of file logging.cpp.

◆ log_to_stdout()

void log_to_stdout ( )
static

Add stdout as output stream to which log messages are written.

Definition at line 129 of file logging.cpp.

◆ log_to_stream()

void log_to_stream ( std::ostream &  os)
static

Add an output stream to which log messages are written.

Definition at line 145 of file logging.cpp.

◆ log_warning()

static void log_warning ( const std::string &  msg)
inlinestatic

Definition at line 519 of file logging.hpp.

◆ max_level() [1/2]

static LoggingLevel max_level ( )
inlinestatic

Get the highest log level that is reported.

Definition at line 491 of file logging.hpp.

◆ max_level() [2/2]

void max_level ( const LoggingLevel  level)
static

Set the highest log level that is reported.

Invocations of log with higher levels will create no output. It creates a warning if the set level is higher than the static compile time level set by LOG_LEVEL_MAX.

Definition at line 88 of file logging.cpp.

◆ operator=()

Logging& operator= ( const Logging )
delete

◆ report_percentage() [1/2]

static int report_percentage ( )
inlinestatic

Get the current percentage for reporting LOG_PROG messages.

Definition at line 498 of file logging.hpp.

◆ report_percentage() [2/2]

void report_percentage ( const int  percentage)
static

set the percentage for reporting LOG_PROG messages.

Definition at line 102 of file logging.cpp.

Member Enumeration Documentation

◆ LoggingLevel

Levels of severity used for logging.

The levels are in ascending order and are used both to signal what kind of message is being logged and to provide a threshold for less important messages that can be filtered out, for example debug messages in the production build of the program. Because some of the filtering is already done at compile time, log messages with a level higher than LOG_LEVEL_MAX do not produce any overhead. See also Logging class for more on this.

Enumerator
kNone 

Special messages that are always logged, e.g. program header.

kError 

Errors, usually non-recoverable. See LOG_ERR.

kWarning 

Warnings if somthing went wront, but program can continue. See LOG_WARN.

kInfo 

Infos, for example when a file was written. See LOG_INFO.

kProgress 

Progess, used in long executing functions. See LOG_PROG.

kMessage 

Basic message. See LOG_MSG.

kMessage1 

Message with level 1. See LOG_MSG1.

kMessage2 

Message with level 2. See LOG_MSG2.

kMessage3 

Message with level 3. See LOG_MSG3.

kMessage4 

Message with level 4. See LOG_MSG4.

kDebug 

Basic debugging message. See LOG_DBG.

kDebug1 

Debugging message with indent level 1 (e.g. for loops). See LOG_DBG1.

kDebug2 

Debugging message with indent level 2. See LOG_DBG2.

kDebug3 

Debugging message with indent level 3. See LOG_DBG3.

kDebug4 

Debugging message with indent level 4. See LOG_DBG4.

Definition at line 405 of file logging.hpp.

Member Data Documentation

◆ buff_

std::ostringstream buff_
protected

Definition at line 585 of file logging.hpp.

◆ count_

long count_ = 0
staticprotected

Definition at line 599 of file logging.hpp.

◆ debug_indent

std::string debug_indent = " "
static

Indention string for Debug Levels 1-4.

Definition at line 508 of file logging.hpp.

◆ details

LoggingDetails details
static
Initial value:
= {
false,
false,
false,
false,
false,
false,
false,
false,
true
}

Settings for which information is included with each log message. See LoggingDetails for usage.

Definition at line 488 of file logging.hpp.

◆ details_

LoggingDetails details_ = {}
protected

Definition at line 590 of file logging.hpp.

◆ file_

std::string file_
protected

Definition at line 586 of file logging.hpp.

◆ fstreams_

std::vector< std::unique_ptr< std::ofstream > > fstreams_
staticprotected

Definition at line 610 of file logging.hpp.

◆ function_

std::string function_
protected

Definition at line 588 of file logging.hpp.

◆ last_clock_

clock_t last_clock_ = 0
staticprotected

Definition at line 602 of file logging.hpp.

◆ level_

LoggingLevel level_ = {}
protected

Definition at line 589 of file logging.hpp.

◆ line_

int line_ = 0
protected

Definition at line 587 of file logging.hpp.

◆ max_level_

Logging::LoggingLevel max_level_ = kDebug4
staticprotected

Definition at line 593 of file logging.hpp.

◆ ostreams_

std::vector< std::ostream * > ostreams_
staticprotected

Definition at line 609 of file logging.hpp.

◆ report_percentage_

int report_percentage_ = 5
staticprotected

Definition at line 596 of file logging.hpp.


The documentation for this class was generated from the following files: