Logger< MSG_BUF_SIZE > Class Template Reference

#include <evo/logger.h>

Inheritance diagram for Logger< MSG_BUF_SIZE >:

Detailed Description

template<uint MSG_BUF_SIZE = 512>
class evo::Logger< MSG_BUF_SIZE >

High performance message logger.

• Efficient lock-free and thread-safe logging
• This uses a background thread that pulls messages from the logger queue and writes to the log file
• Call set_level() to set logging level – messages less severe than this level are ignored (not logged)
• Call start() to open/create the log file and start the background thread
• Call log() or log_direct() to log messages from any thread, or use the helper macros:
  • EVO_LOG_ALERT()
  • EVO_LOG_ERROR()
  • EVO_LOG_WARN()
  • EVO_LOG_INFO()
  • EVO_LOG_DEBUG()
  • EVO_LOG_DEBUG_LOW()
• See: LoggerConsole, LoggerBase

Notes:

• Default logging level: LOG_LEVEL_WARN
• Each message follows this form: [DATE:TIME LEVEL] MESSAGE
  • DATE is the message date in the form: YYYY-MM-DD
  • TIME is the message time in the form: HH:MM:SS
  • LEVEL is the 4 character message severity, one of: ALRT, ERRR, WARN, INFO, DBUG
  • MESSAGE is the message being logged, which may contain newlines
• Messages should not end with a newline
• Each newline in messages should be followed by a space or tab to distinguish multi-line messages
  • Message newlines are written as-is, i.e. are not converted for current platform
• An empty line is written each time a log file is opened (or re-opened)

Template Parameters

MSG_BUF_SIZE

Preallocated size to use for each message – messages within this size don't allocate memory when queued Use MESSAGE_BUFFER_SIZE or call get_message_buffer_size() to get this size See constructor for setting queue size

Example

This example starts a logger and logs some messages – the INFO level message is not logged (and not wastefully formatted) since the log level here is WARN.

#include <evo/logger.h>
using namespace evo;

int main() {
    Logger<> logger;
    logger.set_local_time(true);

    try {
        logger.start("out.log");
    } EVO_CATCH(return 1) // shows exception message if logger can't open file or start thread

    String msg;
    msg.reserve(logger.get_message_buffer_size()); // preallocate message buffer to minimize memory allocations

    EVO_LOG_ERROR(logger, 0, msg.set() << "This is an error -- test " << 123);
    EVO_LOG_WARN(logger, 0, msg.set() << "This is a warning -- test " << 123);
    EVO_LOG_INFO(logger, 0, msg.set() << "This is an info message -- test " << 123);

    return 0; // Logger destructor will flush queued messages and shutdown the background thread
}

The above program appends the following to out.log:

[2000-01-01:00:00:00 ERRR] This is an error -- test 123
[2000-01-01:00:00:00 WARN] This is a warning -- test 123

Note that the above example pre-allocates a string buffer for formatting messages so no memory is allocated at all when formatting and logging messages within that size.

Public Types
typedef Logger< MSG_BUF_SIZE >	This
	This Logger type. More...

Public Member Functions
	Logger (SizeT queue_size=DEFAULT_QUEUE_SIZE)
	Constructor. More...
	~Logger ()
	Destructor, calls shutdown(). More...
bool	check (LogLevel level) const
	Check whether a message with given level will actually be logged. More...
bool	get_error (String &msg)
	Get last error that occurred. More...
uint	get_message_buffer_size () const
	Get message buffer size. More...
bool	log (LogLevel level, const SubString &msg)
	Log a message with given severity level. More...
void	log_direct (LogLevel level, const SubString &msg)
	Log a message with given log level directly without checking the current log level. More...
bool	open (const SubString &path, bool excep=1)
	Open log file but don't start logging thread yet. More...
void	rotate ()
	Set log rotation flag. More...
virtual void	set_level (LogLevel level)
	Set current log level. More...
void	set_local_time (bool local_time)
	Set wheter to convert log date/time values to local time. More...
void	shutdown ()
	Shutdown logging thread. More...
bool	start (const SubString &path, bool excep=1)
	Open log file and start logging thread, which consumes the queue and actually writes to file. More...
bool	start_thread (bool excep=1)
	Start logging thread for already open file, which consumes the queue and actually writes to file. More...

Static Public Attributes
static const SizeT	DEFAULT_QUEUE_SIZE = 256
	Default queue size, override with constructor. More...
static const uint	MESSAGE_BUFFER_SIZE = MSG_BUF_SIZE
	Preallocated buffer size per message – messages within this size don't allocate memory when queued. More...

Protected Attributes
AtomicInt	level_
	Log level, messages less severe than this are ignored (not logged) More...

Member Typedef Documentation

This

typedef Logger<MSG_BUF_SIZE> This

This Logger type.

Constructor & Destructor Documentation

Logger()

Logger ( SizeT  queue_size = DEFAULT_QUEUE_SIZE )

inline

Constructor.

Parameters

queue_size

Queue size to use

~Logger()

~Logger ( )

inline

Destructor, calls shutdown().

Member Function Documentation

check()

bool check ( LogLevel  level ) const

inlineinherited

Check whether a message with given level will actually be logged.

• This is used before calling log_direct() with the message
• Consider using helper macros:
  • EVO_LOG_ALERT()
  • EVO_LOG_ERROR()
  • EVO_LOG_WARN()
  • EVO_LOG_INFO()
  • EVO_LOG_DEBUG()
  • EVO_LOG_DEBUG_LOW()

Parameters

level

Message severity level to check

Returns

Whether given severity level passes current level check, false if a message at this level will be ignored

get_error()

bool get_error ( String &  msg )

inlinevirtual

Get last error that occurred.

• This resets the error message so calling again returns false, unless another error occurred

Parameters

msg	Stores last error message, null if none [out]

Returns

Whether an error occurred, true if error message stored in msg

Reimplemented from LoggerBase.

get_message_buffer_size()

uint get_message_buffer_size ( ) const

inline

Get message buffer size.

• Messages within this size don't allocate memory when queued
• This is useful for pre-allocating a string buffer to minimize memory allocations when logging

Returns

Message buffer size – same as MESSAGE_BUFFER_SIZE

log()

bool log ( LogLevel  level, const SubString &  msg  )

inlineinherited

Log a message with given severity level.

• This calls check() to check whether this message will be logged
• For best performance use check() and log_direct() instead to avoid formatting messages that will not be logged
• Consider using helper macros:
  • EVO_LOG_ALERT()
  • EVO_LOG_ERROR()
  • EVO_LOG_WARN()
  • EVO_LOG_INFO()
  • EVO_LOG_DEBUG()
  • EVO_LOG_DEBUG_LOW()

Parameters

level	Message severity level to use
msg	Message to log

Returns

Whether message was logged, false if message will be ignored due to current log level

log_direct()

void log_direct ( LogLevel  level, const SubString &  msg  )

inlinevirtual

Log a message with given log level directly without checking the current log level.

• This assumes check() was called first to check whether message will be logged
• Consider using helper macros:
  • EVO_LOG_ALERT()
  • EVO_LOG_ERROR()
  • EVO_LOG_WARN()
  • EVO_LOG_INFO()
  • EVO_LOG_DEBUG()
  • EVO_LOG_DEBUG_LOW()

Parameters

level	Message severity level to use
msg	Message to log

Implements LoggerBase.

open()

bool open ( const SubString &  path, bool  excep = 1  )

inline

Open log file but don't start logging thread yet.

• This is useful when about to fork() or daemonize(), but want to open the log first to make sure it works
• Once opened, call start_thread() to start the logging thread

Parameters

path	Log file path to use, can be absolute or relative to current directory
excep	Whether to throw an exception on error, true to always return success else throw exception on error

Returns

Whether successful, false on error opening log file or thread already active (when excep=false)

rotate()

void rotate ( )

inlinevirtual

Set log rotation flag.

• This tells the logging thread to close and re-open the log file between messages
• Linux: Usually called from SIGHUP handler triggered by something like the standard logrotate tool

Reimplemented from LoggerBase.

set_level()

virtual void set_level ( LogLevel  level )

inlinevirtualinherited

Set current log level.

• Log messages with a less severe level than this are ignored (not logged)

Parameters

level

Log level to use – see LogLevel

set_local_time()

void set_local_time ( bool  local_time )

inline

Set wheter to convert log date/time values to local time.

• This conversion adds some small overhead to log writing

shutdown()

void shutdown ( )

inline

Shutdown logging thread.

start()

bool start ( const SubString &  path, bool  excep = 1  )

inline

Open log file and start logging thread, which consumes the queue and actually writes to file.

• This opens the log file and starts the thread that writes queued messages to it
• Once started, if an error occurs in the logging thread get the error message with get_error()
• On success this resets the last error state
• Caution: The logging thread will not survive a fork() or daemonize() – results are undefined in this case if thread is running (Linux/Unix only)
  • To work around this either call this after fork(), or instead call open() before fork() and start_thread() afterwards

Parameters

path	Log file path to use, can be absolute or relative to current directory
excep	Whether to throw an exception on error, true to always return success or throw exception on error

Returns

Whether successful, true if thread started or already running, false on either error opening log file or failed to start thread (when excep=false)

start_thread()

bool start_thread ( bool  excep = 1 )

inline

Start logging thread for already open file, which consumes the queue and actually writes to file.

• open() must be called first to open the log file
• Once started, an error in the logging thread will set an error message retrievable with get_error()
• On success, and if thread wasn't active, this resets the last error state
• Caution: The logging thread will not survive a fork() or daemonize() – results are undefined in this case if thread is running (Linux/Unix only)

Parameters

excep

Whether to throw an exception on error, true to always return success or throw exception on error

Returns

Whether successful, true if thread started or already running, false on either error opening log file or failed to start thread (when excep=false)

Member Data Documentation

DEFAULT_QUEUE_SIZE

const SizeT DEFAULT_QUEUE_SIZE = 256

static

Default queue size, override with constructor.

level_

AtomicInt level_

protectedinherited

Log level, messages less severe than this are ignored (not logged)

MESSAGE_BUFFER_SIZE

const uint MESSAGE_BUFFER_SIZE = MSG_BUF_SIZE

static

Preallocated buffer size per message – messages within this size don't allocate memory when queued.

---

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

• evo/logger.h