cugl::Logger Class Reference

#include <CULogger.h>

Public Types
enum class	Level : int {   NO_MSG = 0 , FATAL_MSG = 1 , ERROR_MSG = 2 , WARN_MSG = 3 ,   INFO_MSG = 4 , DEBUG_MSG = 5 , VERBOSE_MSG = 6 }

Public Member Functions
	Logger ()
	~Logger ()
const std::string	getName () const
const std::string	getPath () const
Level	getLogLevel () const
void	setLogLevel (Level level)
Level	getConsoleLevel () const
void	setConsoleLevel (Level level)
bool	doesAutoFlush () const
void	setAutoFlush (bool value)
void	log (const std::string format,...)
void	log (const char *format,...)
void	log (Level level, const std::string format,...)
void	log (Level level, const char *format,...)
void	flush ()

Static Public Member Functions
static std::shared_ptr< Logger >	open (const std::string channel)
static std::shared_ptr< Logger >	open (const std::string channel, Level level)
static std::shared_ptr< Logger >	get (const std::string channel)
static bool	close (const std::string channel)

Protected Attributes
std::string	_name
std::string	_path
Level	_fileLevel
Level	_consLevel
std::shared_ptr< TextWriter >	_writer
int	_category
char	_timestamp [64]
char *	_buffer
size_t	_capacity
bool	_autof
bool	_open

Static Protected Attributes
static std::unordered_map< std::string, std::shared_ptr< Logger > >	_channels
static int	_nextcategory

Detailed Description

This class provides an interface for fine-grained logging.

This class is an alternative to CULog that provides a lot more features. First of all it provides multiple log channels, each with its own settings. In addition, each channel has its own associated log file. This allows you to keep separate logs for the purposes of analysis and debugging.

Logs are written to the save directory Application#getSaveDirectory. They are named <channel>.log where <channel> is the name of the log channel. Each line of the log file is prefixed by the time up to the nearest microsecond. Messages are only written to the file if they have a log level less than or equal to log level of the channel.

It is possible to log to a file and the output console (e.g. the output stream for CULog) at the same time. The console has its own log level (defined as getConsoleLevel) and will process messages accordingly. Note that the console uses its own timestamps, and so there will be a few microseconds difference between the log file and the console.

Member Enumeration Documentation

Level

enum class cugl::Logger::Level : int

strong

An enum to represent the logging state

Log-levels are used to prioritize messages. Prioriy in this enumeration is assigned higher priority to lower priority. So Level#FATAL_MSG has highest priority while Level#VERBOSE_MSG has the lowest priority. Level#NO_MSG is a special level indicating that no logging should occur.

For any given log channel, you can set it to ignore any messages below a certain priority. For example, if the log channel has a level of Level#INFO_MSG, then it will ignore any messages of the level Level#DEBUG_MSG.

Enumerator
NO_MSG	Do not log anything
FATAL_MSG	Log only fatal errors
ERROR_MSG	Log all errors of any type
WARN_MSG	Log all errors and warnings
INFO_MSG	Log useful information (DEFAULT)
DEBUG_MSG	Log detailed debugging information
VERBOSE_MSG	Log all information available

Constructor & Destructor Documentation

Logger()

cugl::Logger::Logger

(

)

Constructs a new logger object.

This constructor is only initializes the default values, and does not create a usuable logger. It should never be accessed by the user. Use the static method open instead.

~Logger()

cugl::Logger::~Logger ( )

inline

Deletes this logger, releasing all resources.

Member Function Documentation

close()

static bool cugl::Logger::close ( const std::string  channel )

static

Closes the log for the given channel.

Once called, any references to the given log are invalid. If any shared pointers to the log persist, any attempt to write to them will fail.

Parameters

channel

The log channel

Returns

true if the log channel was successfully closed

doesAutoFlush()

bool cugl::Logger::doesAutoFlush ( ) const

inline

Returns true if this logger autoflushes

If a logger does not have autoflush, the messages are not guaranteed to be written to the file until flush is called. Otherwise, the file is written after every message. To improve performance, you may wish to disable this feature if you are writting a large number of messages per animation frame.

Returns

true if this logger autoflushes

flush()

void cugl::Logger::flush

(

)

Flushes any pending messages to the log file.

If a logger has not set doesAutoFlush, the messages are not guaranteed to be written to the file until this method is called. Otherwise, the file is written after every message. To improve performance, you may wish to disable auto flush if you are writting a large number of messages per animation frame.

get()

static std::shared_ptr< Logger > cugl::Logger::get ( const std::string  channel )

static

Returns the logger for the given channel.

If the specified channel is not open, this method returns nullptr.

Parameters

channel

The log channel

Returns

the logger for the given channel.

getConsoleLevel()

Level cugl::Logger::getConsoleLevel ( ) const

inline

Returns the log level for the console.

It is possible to simultaneously log to the log file and the console (e.g. the output stream of CULog). However, messages of a lower priority than this log level will not be written to the console. By default, the console has level Level#NO_MSG, meaning no messages are written to the console.

Note that the console uses its own timestamps, and so there will be a few microseconds difference between the timestamp of a message in the log file and the timestamp in the console.

Returns

the log level for the console.

getLogLevel()

Level cugl::Logger::getLogLevel ( ) const

inline

Returns the log level for the file associate with this logger.

Messages of a lower priority than this log level will not be written to the file. If the level is set to Level#NO_MSG then no messages will be written to the file.

Returns

the log level for the file associate with this logger.

getName()

const std::string cugl::Logger::getName ( ) const

inline

Returns the channel name for this logger

Returns

the channel name for this logger

getPath()

const std::string cugl::Logger::getPath ( ) const

inline

Returns the absolute path to the file for this logger

Returns

the absolute path to the file for this logger

log() [1/4]

void cugl::Logger::log	(	const char *	format,
			...
	)

Sends a message to this logger.

This method has the same structure as printf and CULog. It consists of a format string followed by zero or more arguments to substititute into the string.

The message will be logged with level getLogLevel to the file and getConsoleLevel to the console.

Parameters

format	The formatting string
...	The printf-style subsitution arguments

log() [2/4]

void cugl::Logger::log	(	const std::string	format,
			...
	)

Sends a message to this logger.

This method has the same structure as printf and CULog. It consists of a format string followed by zero or more arguments to substititute into the string.

The message will be logged with level getLogLevel to the file and getConsoleLevel to the console.

Parameters

format	The formatting string
...	The printf-style subsitution arguments

log() [3/4]

void cugl::Logger::log	(	Level	level,
		const char *	format,
			...
	)

Sends a message to this logger.

This method has the same structure as printf and CULog. It consists of a format string followed by zero or more arguments to substititute into the string.

The message will be logged with given level to both the file and the console. The message must be of equal priority or higher than getLogLevel or getConsoleLevel to appear in the file or on the console, respectively.

Parameters

level	The priority for this log message
format	The formatting string
...	The printf-style subsitution arguments

log() [4/4]

void cugl::Logger::log	(	Level	level,
		const std::string	format,
			...
	)

Sends a message to this logger.

This method has the same structure as printf and CULog. It consists of a format string followed by zero or more arguments to substititute into the string.

The message will be logged with given level to both the file and the console. The message must be of equal priority or higher than getLogLevel or getConsoleLevel to appear in the file or on the console, respectively.

Parameters

level	The priority for this log message
format	The formatting string
...	The printf-style subsitution arguments

open() [1/2]

static std::shared_ptr< Logger > cugl::Logger::open ( const std::string  channel )

static

Returns a new logger for the given channel.

If this channel already exists, this method will return the existing logger for that channel. A new logger will always start with level Level#INFO_MSG for the log file and Level#NO_MSG for the console.

Parameters

channel

The log channel

Returns

a new logger for the given channel.

open() [2/2]

static std::shared_ptr< Logger > cugl::Logger::open ( const std::string  channel, Level  level  )

static

Returns a new logger for the given channel and log level.

The level will apply to the log file. The console will always have level Level#NO_MSG unless otherwise set by setConsoleLevel.

If this channel already exists, this method will return the existing logger for that channel. It will also update the log level of that channel to the one specified.

Parameters

channel	The log channel
level	The log level

Returns

a new logger for the given channel and log level.

setAutoFlush()

void cugl::Logger::setAutoFlush

(

bool

value

)

Sets whether this logger should autoflush

If a logger does not have autoflush, the messages are not guaranteed to be written to the file until flush is called. Otherwise, the file is written after every message. To improve performance, you may wish to disable this feature if you are writting a large number of messages per animation frame.

Parameters

value

whether this logger should autoflush

setConsoleLevel()

void cugl::Logger::setConsoleLevel

(

Level

level

)

Sets the log level for the console.

It is possible to simultaneously log to the log file and the console (e.g. the output stream of CULog). However, messages of a lower priority than this log level will not be written to the console. By default, the console has level Level#NO_MSG, meaning no messages are written to the console.

Note that the console uses its own timestamps, and so there will be a few microseconds difference between the timestamp of a message in the log file and the timestamp in the console.

Parameters

level

the log level for the console.

setLogLevel()

void cugl::Logger::setLogLevel

(

Level

level

)

Sets the log level for the file associate with this logger.

Messages of a lower priority than this log level will not be written to the file. If the level is set to Level#NO_MSG then no messages will be written to the file.

Changing the value always flushes any pending messages to the file.

Parameters

level

the level for the file associate with this logger

Member Data Documentation

_autof

bool cugl::Logger::_autof

protected

Whether auto flush is active

_buffer

char* cugl::Logger::_buffer

protected

The buffer for formatting log messages

_capacity

size_t cugl::Logger::_capacity

protected

The capacity of the formatting buffer

_category

int cugl::Logger::_category

protected

The SDL category for this logger

_channels

std::unordered_map<std::string, std::shared_ptr<Logger> > cugl::Logger::_channels

staticprotected

The list of all active logs

_consLevel

Level cugl::Logger::_consLevel

protected

The console log level of this logger

_fileLevel

Level cugl::Logger::_fileLevel

protected

The file log level of this logger

_name

std::string cugl::Logger::_name

protected

The name of this log channel

_nextcategory

int cugl::Logger::_nextcategory

staticprotected

The SDL category to assign to the next allocated log

_open

bool cugl::Logger::_open

protected

Whether this channel is still open.

_path

std::string cugl::Logger::_path

protected

The path to the log file

_timestamp

char cugl::Logger::_timestamp[64]

protected

A buffer for writting timestamp information

_writer

std::shared_ptr<TextWriter> cugl::Logger::_writer

protected

The text writer for outputing to a file

---

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

• /Users/wmwhite/Developer/CUGL/include/cugl/util/CULogger.h