VLogger Class Reference

The VLogger class provides the static APIs for configuring the logging system, adding, removing, and finding appenders and loggers, etc. More...

#include <vlogger.h>

List of all members.

Static Public Member Functions
static void	registerLogAppenderFactory (const VString &appenderKind, VLogAppenderFactoryPtr factory)
	Registers an appender factory.
static void	configure (const VFSNode &baseLogDirectory, const VSettingsNode &loggingSettings)
	Configures logging by reading settings info.
static void	shutdown ()
	This function should always be called when terminating the application, as late as possible to ensure that no attempt is made to log after this is called.
static void	installNewLogAppender (const VSettingsNode &appenderSettings, const VSettingsNode &appenderDefaults)
	Instantiates and registers an appender from settings, via the already-registered factory for the concrete VLogAppender subclass indicated by "kind".
static void	installNewNamedLogger (const VSettingsNode &loggerSettings)
	Instantiates and registers a VNamedLogger from settings.
static void	installNewNamedLogger (const VString &name, int level, const VStringVector &appenderNames)
	Instantiates and registers a VNamedLogger.
static void	installNewNamedLogger (const VString &name, int level, const VString &appenderName)
	Instantiates and registers a VNamedLogger.
static void	registerLogAppender (VLogAppenderPtr appender, bool asDefaultAppender=false)
	Registers the supplied appender.
static void	registerGlobalAppender (VLogAppenderPtr appender, bool asDefaultAppender=false)
	Registers the supplied appender, and also adds it to the list of global appenders to which all loggers implicitly emit their filtered output.
static void	registerLogger (VNamedLoggerPtr namedLogger, bool asDefaultLogger=false)
	Registers the supplied logger.
static void	deregisterLogAppender (VLogAppenderPtr appender)
	Removes the specified appender from the registry.
static void	deregisterLogAppender (const VString &name)
	Finds the specified appender by name, and if found, removes it from the registry.
static void	deregisterLogger (VNamedLoggerPtr namedLogger)
	Removes the specified logger from the registry.
static void	deregisterLogger (const VString &name)
	Finds the specified logger by name, and if found, removes it from the registry.
static void	checkMaxActiveLogLevelForRemovedLogger (int removedActiveLevel)
	Used internally for bookkeeping when a logger is removed, to maintain the "max active log level" optimization.
static void	checkMaxActiveLogLevelForChangedLogger (int oldActiveLevel, int newActiveLevel)
	Used internally for bookkeeping when a logger's level is changed, to maintain the "max active log level" optimization.
static bool	isDefaultLogLevelActive (int level)
	Returns true if the default logger is active for the specified level.
static bool	isLogLevelActive (int level)
	Returns true if any registered logger is active for the specified level.
static VNamedLoggerPtr	getDefaultLogger ()
	Returns the default logger; creates, installs, and returns a new one if there is no default logger.
static void	setDefaultLogger (VNamedLoggerPtr namedLogger)
	Makes the specified logger the default logger.
static VNamedLoggerPtr	getLogger (const VString &name)
	Returns a logger by looking for the one specified, or returns the default logger if none with that name exists.
static VNamedLoggerPtr	findDefaultLogger ()
	Returns the default logger, if it already exists; null otherwise.
static VNamedLoggerPtr	findDefaultLoggerForLevel (int level)
	Returns the default logger, if it already exists, and is active for the specified level; null otherwise.
static VNamedLoggerPtr	findNamedLogger (const VString &name)
	Returns the specified logger, if it exists; null otherwise.
static VNamedLoggerPtr	findNamedLoggerForLevel (const VString &name, int level)
	Returns the specified logger, if it exists AND it is active for the specified level; null otherwise.
static VLogAppenderPtr	getDefaultAppender ()
	Returns the default appender; creates, installs, and returns a new VCoutAppender if there is no default appender.
static VLogAppenderPtr	getAppender (const VString &appenderName)
	Returns an appender by looking for the one specified, or returns the default appender if none with that name exists.
static VLogAppenderPtrList	getAllAppenders ()
	Returns a new list containing all appenders including the global appenders.
static VLogAppenderPtr	findDefaultAppender ()
	Returns the default appender, if it already exists; null otherwise.
static VLogAppenderPtr	findAppender (const VString &name)
	Returns the specified appender, if it exists; null otherwise.
static const VFSNode &	getBaseLogDirectory ()
	Returns the directory node specifying the base directory where file-oriented appenders should create files (or a file hierarchy) unless a specific path is configured for the appender.
static VBentoNode *	commandGetInfo ()
	Returns a Bento structure describing the logging structures in effect, for diagnostic output.
static VString	commandGetInfoString ()
	Returns a string taken from the Bento results of commandGetInfo().
static void	commandNewAppender (const VString &appenderName, const VString &kind, const VString &appenderParam)
	Calls through to installNewLogAppender().
static void	commandRemoveAppender (const VString &appenderName)
	Calls through to deregisterAppender().
static void	commandRollAppender (const VString &appenderName)
	Finds the specified (or all, if appenderName is empty) VRollingFileLogAppender and tells them to roll over to a new file.
static void	commandNewLogger (const VString &loggerName, const VStringVector &appenderNames)
	Calls through to installNewNamedLogger().
static void	commandRemoveLogger (const VString &loggerName)
	Calls through to deregisterLogger().
static void	commandSetLoggerAppenders (const VString &loggerName, const VStringVector &appenderNames)
	Calls through to clearAppenders() and setAppender() for the specified logger.
static void	commandAddLoggerAppenders (const VString &loggerName, const VStringVector &appenderNames)
	Calls through to addAppender() for the specified logger.
static void	commandRemoveLoggerAppenders (const VString &loggerName, const VStringVector &appenderNames)
	Calls through to removeAppender() for the specified logger.
static void	commandSetLogLevel (const VString &loggerName, int level)
	Calls through to setLevel for the specified (or all, if loggerName is empty) loggers.
static void	commandSetPrintStackLevel (const VString &loggerName, int printStackLevel, int count, const VDuration &timeLimit)
	Calls through to setPrintStackInfo() for the specified (or all, if loggerName is empty) loggers.
static void	emitToGlobalAppenders (int level, const char *file, int line, bool emitMessage, const VString &message, const VString &specifiedLoggerName, const VString &actualLoggerName, bool emitRawLine, const VString &rawLine)
static VString	getCleansedLoggerName (const VString &s)
Friends
class	VLoggerUnit
bool	VNamedLogger::isDefaultLogger () const
bool	VLogAppender::isDefaultAppender () const

---

Detailed Description

The VLogger class provides the static APIs for configuring the logging system, adding, removing, and finding appenders and loggers, etc.

This is the primary outward facing class for logging beyond the use of the macros that generate output.

Definition at line 718 of file vlogger.h.

---

Member Function Documentation

void VLogger::registerLogAppenderFactory	(	const VString &	appenderKind,
		VLogAppenderFactoryPtr	factory
	)		[static]

Registers an appender factory.

If this is done prior to a call to configure(), the factory can be used to dynamically instantiate an appender from the configuration. The configure() method itself registers the appender factories supplied by this module. You only need to register factories for custom appenders you have written, and only if you want them to be accessible during configure().

Parameters:

appenderKind	a unique short string defining the appender class as it will be specified in the config settings XML; e.g., "cout", "file", etc.
factory	an appender factory

Definition at line 385 of file vlogger.cpp.

void VLogger::configure	(	const VFSNode &	baseLogDirectory,
		const VSettingsNode &	loggingSettings
	)		[static]

Configures logging by reading settings info.

The supplied baseLogDirectory can be an empty path, but otherwise it specifies a directory within which any file-based appenders should store their files and subdirectories; they will obtain this implicit base path from the global variable gBaseLogDirectory. The supplied settings node has the following child nodes:

• A child node named "appender" defining each VLogAppender to be instantiated and registered.
  • Appender nodes have at a minimum a "name" string property and a "kind" string property.
  • All appenders have an optional "format-output" boolean property that, if false, specifies that the appender should not apply any formatting (such as a timestamp, level name, etc.) to its output. The default behavior is to format the output.
  • Other properties required or optional depend on the concrete appender class features.
• A child node named "logger" defining each VNamedLogger to be instantiated and registered.
  • Logger nodes have at a minimum a "name" string property and a "level" int property.
  • Typically they also have an "appender" string property that defines the appender to use.
  • For multiple appenders, the logger node can have child nodes named "appender" that have a "name" string property.

    Parameters:

    baseLogDirectory	the directory structure where file-based appenders should write (see description above)
    loggingSettings	the settings to process

Definition at line 391 of file vlogger.cpp.

References VString::EMPTY(), VFSNode::getPath(), installNewLogAppender(), installNewNamedLogger(), NULL, and registerLogAppenderFactory().

void VLogger::shutdown

(

)

[static]

This function should always be called when terminating the application, as late as possible to ensure that no attempt is made to log after this is called.

It cleans up and removes all logging objects.

Definition at line 431 of file vlogger.cpp.

void VLogger::installNewLogAppender	(	const VSettingsNode &	appenderSettings,
		const VSettingsNode &	appenderDefaults
	)		[static]

Instantiates and registers an appender from settings, via the already-registered factory for the concrete VLogAppender subclass indicated by "kind".

The settings node has the properties mentioned above for configure(). If there is no default appender at the time of this call, the instantiated appender becomes the default appender.

Parameters:

appenderSettings	the settings to process
appenderDefaults	optional default properties for the kind of appender specified in appenderSettings

Definition at line 326 of file vlogger.cpp.

References registerLogAppender(), and VMutexLocker::unlock().

void VLogger::installNewNamedLogger

(

const VSettingsNode &

loggerSettings

)

[static]

Instantiates and registers a VNamedLogger from settings.

The settings node has the properties mentioned above for configure(). If there is no default logger at the time of this call, the instantiated appender becomes the default logger.

Parameters:

loggerSettings

the settings to process

Definition at line 338 of file vlogger.cpp.

References VString::EMPTY(), VLoggerLevel::fromString(), VString::isNotEmpty(), VLoggerLevel::OFF, and VDuration::POSITIVE_INFINITY().

void VLogger::installNewNamedLogger	(	const VString &	name,
		int	level,
		const VStringVector &	appenderNames
	)		[static]

Instantiates and registers a VNamedLogger.

If there is no default logger at the time of this call, the instantiated appender becomes the default logger.

Parameters:

name	the name for the logger; if an existing logger with that name already exists, it will be replaced in the map of registered loggers
level	the log leve for the logger
appenderNames	a list of appender names to which this logger will emit its filtered output

Definition at line 370 of file vlogger.cpp.

void VLogger::installNewNamedLogger	(	const VString &	name,
		int	level,
		const VString &	appenderName
	)		[static]

Instantiates and registers a VNamedLogger.

If there is no default logger at the time of this call, the instantiated logger becomes the default logger.

Parameters:

name	the name for the logger; if an existing logger with that name already exists, it will be replaced in the map of registered loggers
level	the log leve for the logger
appenderName	an appender name to which this logger will emit its filtered output

Definition at line 378 of file vlogger.cpp.

References installNewNamedLogger().

void VLogger::registerLogAppender	(	VLogAppenderPtr	appender,
		bool	asDefaultAppender = false
	)		[static]

Registers the supplied appender.

If there is no default appender at the time of this call, the appender becomes the default appender.

Parameters:

appender	the appender to register
asDefaultAppender	if true, the appender becomes the default appender

Definition at line 445 of file vlogger.cpp.

void VLogger::registerGlobalAppender	(	VLogAppenderPtr	appender,
		bool	asDefaultAppender = false
	)		[static]

Registers the supplied appender, and also adds it to the list of global appenders to which all loggers implicitly emit their filtered output.

If there is no default appender at the time of this call, the appender becomes the default appender.

Parameters:

appender	the appender to register
asDefaultAppender	if true, the appender becomes the default appender

Definition at line 451 of file vlogger.cpp.

void VLogger::registerLogger	(	VNamedLoggerPtr	namedLogger,
		bool	asDefaultLogger = false
	)		[static]

Registers the supplied logger.

If there is no default logger at the time of this call, the logger becomes the default logger.

Parameters:

namedLogger	the logger to register
asDefaultLogger	if true (or if there is no default logger yet), it will be the default logger

Definition at line 457 of file vlogger.cpp.

void VLogger::deregisterLogAppender

(

VLogAppenderPtr

appender

)

[static]

Removes the specified appender from the registry.

Parameters:

appender

the appender to deregister

Definition at line 463 of file vlogger.cpp.

void VLogger::deregisterLogAppender

(

const VString &

name

)

[static]

Finds the specified appender by name, and if found, removes it from the registry.

Parameters:

name	the name of the appender to find and deregister

Definition at line 483 of file vlogger.cpp.

References deregisterLogAppender(), and findAppender().

void VLogger::deregisterLogger

(

VNamedLoggerPtr

namedLogger

)

[static]

Removes the specified logger from the registry.

Parameters:

namedLogger

the logger to deregister

Definition at line 491 of file vlogger.cpp.

void VLogger::deregisterLogger

(

const VString &

name

)

[static]

Finds the specified logger by name, and if found, removes it from the registry.

Parameters:

name	the name of the logger to find and deregister

Definition at line 507 of file vlogger.cpp.

References deregisterLogger(), and findNamedLogger().

void VLogger::checkMaxActiveLogLevelForRemovedLogger

(

int

removedActiveLevel

)

[static]

Used internally for bookkeeping when a logger is removed, to maintain the "max active log level" optimization.

Parameters:

removedActiveLevel

the log level of the logger that is being removed

Definition at line 834 of file vlogger.cpp.

void VLogger::checkMaxActiveLogLevelForChangedLogger	(	int	oldActiveLevel,
		int	newActiveLevel
	)		[static]

Used internally for bookkeeping when a logger's level is changed, to maintain the "max active log level" optimization.

Parameters:

oldActiveLevel	the old log level of the logger that is changing
newActiveLevel	the new log level of the logger that is changing

Definition at line 850 of file vlogger.cpp.

bool VLogger::isDefaultLogLevelActive

(

int

level

)

[static]

Returns true if the default logger is active for the specified level.

Parameters:

level

the level to check

Returns:

true if the default logger would log at that level

Definition at line 515 of file vlogger.cpp.

References getDefaultLogger(), and isLogLevelActive().

bool VLogger::isLogLevelActive

(

int

level

)

[static]

Returns true if any registered logger is active for the specified level.

Parameters:

level

the level to check

Returns:

true if some registered logger would log at that level

Definition at line 520 of file vlogger.cpp.

VNamedLoggerPtr VLogger::getDefaultLogger

(

)

[static]

Returns the default logger; creates, installs, and returns a new one if there is no default logger.

Returns:

the default logger (@ NotNull)

Definition at line 526 of file vlogger.cpp.

References VLoggerLevel::INFO.

void VLogger::setDefaultLogger

(

VNamedLoggerPtr

namedLogger

)

[static]

Makes the specified logger the default logger.

Parameters:

namedLogger

the logger to make the default logger

Definition at line 547 of file vlogger.cpp.

VNamedLoggerPtr VLogger::getLogger

(

const VString &

name

)

[static]

Returns a logger by looking for the one specified, or returns the default logger if none with that name exists.

Parameters:

name	the name of the logger to find

Returns:

the found logger, or the default logger if not found (@ NotNull)

Definition at line 555 of file vlogger.cpp.

References findNamedLogger(), and getDefaultLogger().

VNamedLoggerPtr VLogger::findDefaultLogger

(

)

[static]

Returns the default logger, if it already exists; null otherwise.

Returns:

the default logger (@ Nullable)

Definition at line 566 of file vlogger.cpp.

VNamedLoggerPtr VLogger::findDefaultLoggerForLevel

(

int

level

)

[static]

Returns the default logger, if it already exists, and is active for the specified level; null otherwise.

Parameters:

level

the level to check as active for the default logger

Returns:

the default logger (@ Nullable)

Definition at line 572 of file vlogger.cpp.

References VLoggerLevel::INFO.

VNamedLoggerPtr VLogger::findNamedLogger

(

const VString &

name

)

[static]

Returns the specified logger, if it exists; null otherwise.

Parameters:

name	the name of the logger to find

Returns:

a logger (@ Nullable)

Definition at line 583 of file vlogger.cpp.

VNamedLoggerPtr VLogger::findNamedLoggerForLevel	(	const VString &	name,
		int	level
	)		[static]

Returns the specified logger, if it exists AND it is active for the specified level; null otherwise.

Parameters:

name	the name of the logger to find
level	the level to check as active for the found logger

Returns:

a logger (@ Nullable)

Definition at line 589 of file vlogger.cpp.

References findDefaultLoggerForLevel(), findNamedLogger(), and isLogLevelActive().

VLogAppenderPtr VLogger::getDefaultAppender

(

)

[static]

Returns the default appender; creates, installs, and returns a new VCoutAppender if there is no default appender.

Returns:

the default appender (@ NotNull)

Definition at line 621 of file vlogger.cpp.

References VString::EMPTY().

VLogAppenderPtr VLogger::getAppender

(

const VString &

appenderName

)

[static]

Returns an appender by looking for the one specified, or returns the default appender if none with that name exists.

Parameters:

appenderName

the name of the appender to find

Returns:

the found appender, or the appender logger if not found (@ NotNull)

Definition at line 632 of file vlogger.cpp.

References getDefaultAppender().

VLogAppenderPtrList VLogger::getAllAppenders

(

)

[static]

Returns a new list containing all appenders including the global appenders.

It's possible for the list to be empty if no appenders have been registered. All values will be non-null shared_ptr copies.

Returns:

the list of all appenders

Definition at line 646 of file vlogger.cpp.

VLogAppenderPtr VLogger::findDefaultAppender

(

)

[static]

Returns the default appender, if it already exists; null otherwise.

Returns:

the default appender (@ Nullable)

Definition at line 665 of file vlogger.cpp.

VLogAppenderPtr VLogger::findAppender

(

const VString &

name

)

[static]

Returns the specified appender, if it exists; null otherwise.

Parameters:

name	the name of the appender to find

Returns:

an appender (@ Nullable)

Definition at line 671 of file vlogger.cpp.

VBentoNode * VLogger::commandGetInfo

(

)

[static]

Returns a Bento structure describing the logging structures in effect, for diagnostic output.

Returns:

obvious

Definition at line 686 of file vlogger.cpp.

VString VLogger::commandGetInfoString

(

)

[static]

Returns a string taken from the Bento results of commandGetInfo().

Returns:

obvious

Definition at line 722 of file vlogger.cpp.

---

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

• vlogger.h
• vlogger.cpp