LogCabin::Core::Debug Namespace Reference

Namespaces
namespace	Internal
Classes
struct	DebugMessage
	When LogCabin wants to print a log message, this is the information that gets included. More...
Enumerations
enum	LogLevel {   SILENT,   ERROR,   WARNING,   NOTICE,   VERBOSE }
	The levels of verbosity for log messages. More...
Functions
std::string	getLogFilename ()
	Return the filename given to the last successful call to setLogFilename(), or the empty string if none.
std::string	setLogFilename (const std::string &filename)
	Open the given file by name and append future debug log messages to it.
std::string	reopenLogFromFilename ()
	Called to rotate the log file.
FILE *	setLogFile (FILE *newFile)
	Change the file on which debug log messages are written.
std::function< void(DebugMessage)>	setLogHandler (std::function< void(DebugMessage)> newHandler)
	Accept log messages on the given callback instead of writing them to a file.
std::vector< std::pair < std::string, std::string > >	getLogPolicy ()
	Return the current log policy (as set by a previous call to setLogPolicy).
void	setLogPolicy (const std::vector< std::pair< std::string, std::string >> &newPolicy)
	Specify the log messages that should be displayed for each filename.
void	setLogPolicy (const std::initializer_list< std::pair< std::string, std::string >> &newPolicy)
	See setLogPolicy.
std::vector< std::pair < std::string, std::string > >	logPolicyFromString (const std::string &in)
	Build a log policy from its string representation.
std::string	logPolicyToString (const std::vector< std::pair< std::string, std::string >> &policy)
	Serialize a log policy into a string representation.
std::ostream &	operator<< (std::ostream &ostream, LogLevel level)
	Output a LogLevel to a stream.
bool	isLogging (LogLevel level, const char *fileName)
	Return whether the current logging configuration includes messages of the given level for the given filename.
void	log (LogLevel level, const char *fileName, uint32_t lineNum, const char *functionName, const char *message)
	Unconditionally log the given message to stderr.
Variables
std::string	processName
	A short name to be used in log messages to identify this process.

---

Enumeration Type Documentation

enum LogCabin::Core::Debug::LogLevel

The levels of verbosity for log messages.

Higher values are noisier.

Since:

LogCabin v1.1.0. New levels may be added in future minor releases (adding a new level is considered backwards-compatible), so use 'default' values in switch statements.

Enumerator:

SILENT	This log level is just used for disabling all log messages, which is really only useful in unit tests.
ERROR	Bad stuff that shouldn't happen. The system broke its contract to users in some way or some major assumption was violated.
WARNING	Messages at the WARNING level indicate that, although something went wrong or something unexpected happened, it was transient and recoverable.
NOTICE	A system message that might be useful for administrators and developers.
VERBOSE	Messages at the VERBOSE level don't necessarily indicate that anything went wrong, but they could be useful in diagnosing problems.

Definition at line 47 of file Debug.h.

---

Function Documentation

std::string LogCabin::Core::Debug::getLogFilename

(

)

Return the filename given to the last successful call to setLogFilename(), or the empty string if none.

Since:

LogCabin v1.1.0.

Definition at line 258 of file Debug.cc.

std::string LogCabin::Core::Debug::setLogFilename

(

const std::string &

filename

)

Open the given file by name and append future debug log messages to it.

Note that if a handler is set with setLogHandler, this file will not be used.

Parameters:

filename

Name of file. If it already exists, new messages will be appended at the end. If the file is already open, this will re-open it (useful for rotating logs).

Returns:

Error message if errors were encountered opening the file, otherwise an empty string indicates success.

Since:

LogCabin v1.1.0.

Definition at line 265 of file Debug.cc.

std::string LogCabin::Core::Debug::reopenLogFromFilename

(

)

Called to rotate the log file.

If there was a previous call to setLogFilename(), this will reopen that file by name, returning any errors. Otherwise, it will do nothing.

Returns:

Error message if errors were encountered in reopening the file, otherwise an empty string indicates success.

Since:

LogCabin v1.1.0.

Definition at line 291 of file Debug.cc.

FILE * LogCabin::Core::Debug::setLogFile

(

FILE *

newFile

)

Change the file on which debug log messages are written.

Note that if a handler is set with setLogHandler, this file will not be used. If a filename has been set with setLogFilename(), this will clear it.

Parameters:

newFile

Handle to open file where log messages will be written.

Returns:

Handle to previous log file (initialized to stderr on process start).

Definition at line 301 of file Debug.cc.

std::function< void(DebugMessage)> LogCabin::Core::Debug::setLogHandler

(

std::function< void(DebugMessage)>

newHandler

)

Accept log messages on the given callback instead of writing them to a file.

Call this again with an empty std::function() to clear it.

Parameters:

newHandler

Callback invoked once per log message, possibly concurrently.

Returns:

Previous callback (initialized to empty std::function on process start).

Definition at line 311 of file Debug.cc.

std::vector< std::pair< std::string, std::string > > LogCabin::Core::Debug::getLogPolicy

(

)

Return the current log policy (as set by a previous call to setLogPolicy).

Note that this may be empty, indicating that the default level of NOTICE is in use.

Since:

LogCabin v1.1.0.

Definition at line 320 of file Debug.cc.

void LogCabin::Core::Debug::setLogPolicy

(

const std::vector< std::pair< std::string, std::string >> &

newPolicy

)

Specify the log messages that should be displayed for each filename.

This first component is a pattern; the second is a log level. A filename is matched against each pattern in order: if the filename starts with or ends with the pattern, the corresponding log level defines the most verbose messages that are to be displayed for the file. If a filename matches no pattern, its log level will default to NOTICE.

Definition at line 327 of file Debug.cc.

void LogCabin::Core::Debug::setLogPolicy

(

const std::initializer_list< std::pair< std::string, std::string >> &

newPolicy

)

See setLogPolicy.

Definition at line 336 of file Debug.cc.

std::vector< std::pair< std::string, std::string > > LogCabin::Core::Debug::logPolicyFromString

(

const std::string &

in

)

Build a log policy from its string representation.

Parameters:

in	A string of the form "pattern@level,pattern@level,level". The pattern is separated from the level by an at symbol. Multiple rules are separated by comma. A rule with an empty pattern (match all) does not need an at symbol.

Returns:

Logging policy based on string description.

Since:

LogCabin v1.1.0.

Definition at line 344 of file Debug.cc.

std::string LogCabin::Core::Debug::logPolicyToString

(

const std::vector< std::pair< std::string, std::string >> &

policy

)

Serialize a log policy into a string representation.

Parameters:

policy

Logging policy in the format required by setLogPolicy.

Returns:

String representation as accepted by logPolicyFromString.

Since:

LogCabin v1.1.0.

Definition at line 367 of file Debug.cc.

std::ostream & LogCabin::Core::Debug::operator<<	(	std::ostream &	ostream,
		LogLevel	level
	)

Output a LogLevel to a stream.

Having this improves gtest error messages.

Definition at line 396 of file Debug.cc.

bool LogCabin::Core::Debug::isLogging	(	LogLevel	level,
		const char *	fileName
	)

Return whether the current logging configuration includes messages of the given level for the given filename.

This is normally called by LOG().

Warning:

fileName must be a string literal!

Parameters:

level	The log level to query.
fileName	This should be a string literal, probably __FILE__, since the result of this call will be cached based on the memory address pointed to by 'fileName'.

Definition at line 403 of file Debug.cc.

void LogCabin::Core::Debug::log	(	LogLevel	level,
		const char *	fileName,
		uint32_t	lineNum,
		const char *	functionName,
		const char *	message
	)

Unconditionally log the given message to stderr.

This is normally called by LOG().

Parameters:

level	The level of importance of the message.
fileName	The output of __FILE__.
lineNum	The output of __LINE__.
functionName	The output of __FUNCTION__.
message	A descriptive message to print, which should not include a line break at the end.

Definition at line 418 of file Debug.cc.

---

Variable Documentation

std::string LogCabin::Core::Debug::processName

A short name to be used in log messages to identify this process.

This defaults to the UNIX process ID.

Definition at line 106 of file Debug.cc.