A simple logging class. More...

#include <Wt/WLogger.h>

Classes
class	Field
	Class that holds the configuration for a single field. More...

struct	Sep
	Class that indicates a field separator. More...

struct	TimeStamp
	Class that indicates a time stamp. More...

Public Member Functions
	WLogger ()
	Creates a new logger. More...

	~WLogger ()
	Destructor.

void	setStream (std::ostream &o)
	Sets the output stream. More...

void	setFile (const std::string &path)
	Sets the output file. More...

void	configure (const std::string &config)
	Configures what things are logged. More...

void	addField (const std::string &name, bool isString)
	Adds a field. More...

const std::vector< Field > &	fields () const
	Returns the field list.

WLogEntry	entry (const std::string &type) const
	Starts a new log entry. More...

bool	logging (const std::string &type) const
	Returns whether messages of a given type are logged. More...

bool	logging (const char *type) const
	Returns whether messages of a given type are logged. More...

bool	logging (const std::string &type, const std::string &scope) const
	Returns whether messages of a given type and scope are logged. More...

void	setUseLock (bool enable)
	Enabled the logger to take locks when logging. More...

bool	useLock () const
	Returns whether the logger use a mutex. More...

Static Public Attributes
static const Sep	sep = WLogger::Sep()
	Field separator constant. More...

static const TimeStamp	timestamp = WLogger::TimeStamp()
	Timestamp field constant. More...

Related Functions
(Note that these are not member functions.)
WLogEntry	log (const std::string &type)
	Logging function. More...

Detailed Description

A simple logging class.

This class logs events to a stream in a flexible way. It allows to create log files using the commonly used Common Log Format or Combined Log Format, but provides a general way for logging entries that consists of a fixed number of fields.

It is used by Wt to create the application log (WApplication::log()), and built-in httpd access log.

To use this class for custom logging, you should instantiate a logger, add one or more field definitions using addField(), and set an output stream using setStream() or setFile(). To stream data to the logger, use entry() to start formatting a new entry.

Usage example:

// Setup the logger
Wt::WLogger logger;
logger.addField("datetime", false);
logger.addField("session", false);
logger.addField("type", false);
logger.addField("message", true);
 
logger.setFile("/tmp/mylog.txt");
 
// Add an entry
Wt::WLogEntry entry = logger.entry();
entry << Wt::WLogger::timestamp << Wt::WLogger::sep
      << '[' << wApp->sessionId() << ']' << Wt::WLogger::sep
      << '[' << "notice" << ']' << Wt::WLogger::sep
      << "Succesfully started.";

See also: WApplication::log()

Constructor & Destructor Documentation

◆ WLogger()

Wt::WLogger::WLogger ( )

Creates a new logger.

This creates a new logger, which defaults to logging to stderr.

Member Function Documentation

◆ addField()

void Wt::WLogger::addField	(	const std::string &	name,
		bool	isString
	)

Adds a field.

Add a field to the logger. When isString is true, values will be quoted.

◆ configure()

void Wt::WLogger::configure ( const std::string & config )

Configures what things are logged.

The configuration is a string that defines rules for enabling or disabling certain logging. It is a white-space delimited list of rules, and each rule is of the form:

[-]level : enables (or disables) logging of messages of the given level; '*' is a wild-card that matches all levels
[-]level:scope : enables (or disables) logging of messages of the given level and scope; '*' is a wild-card that matches all levels or scopes.

The default configuration is "* -debug", i.e. by default everything is logged, except for "debug" messages.

Some other examples:

"* -debug debug:wthttp": logs everything, including debugging messages of scope "wthttp", but no other debugging messages.
"* -info -debug": disables logging of info messages in addition to debugging messages.

Note: The standard logging is typically configured in the configuration file, in the <log-config> block.

◆ entry()

WLogEntry Wt::WLogger::entry ( const std::string & type ) const

Starts a new log entry.

Returns a new entry. The entry is logged in the destructor of the entry (i.e. when the entry goes out of scope).

The type reflects a logging level. You can freely choose a type, but these are commonly used inside the library:

"debug": debugging info (suppressed by default)
"info": informational notices
"warning": warnings (potentially wrong API use)
"secure": security-related events
"error": errors (wrong API use, unexpected protocol messages)
"fatal": fatal errors (terminate the session)

◆ logging() [1/3]

bool Wt::WLogger::logging ( const char * type ) const

Returns whether messages of a given type are logged.

Returns true if messages of the given type are logged. It may be that not messages of all scopes are logged.

See also: configure()

◆ logging() [2/3]

bool Wt::WLogger::logging ( const std::string & type ) const

Returns whether messages of a given type are logged.

Returns true if messages of the given type are logged. It may be that not messages of all scopes are logged.

See also: configure()

◆ logging() [3/3]

bool Wt::WLogger::logging	(	const std::string &	type,
		const std::string &	scope
	)		const

Returns whether messages of a given type and scope are logged.

See also: configure()

◆ setFile()

void Wt::WLogger::setFile ( const std::string & path )

Sets the output file.

Opens a file output stream for path. The default logger outputs to stderr.

This logs a message notifying the user whether the file was successfully opened for writing to the previous ostream (usually std::cerr).

If you want to suppress the info message, you can configure the logger with "-info:WLogger". The error when the file was not successfully opened is logged at the error log level.

Note: If the previous ostream was a file set with this method, the message will be logged to std::cerr instead of the previous file, because the previous file is closed first.

See also: setStream()

◆ setStream()

void Wt::WLogger::setStream ( std::ostream & o )

Sets the output stream.

The default logger outputs to stderr.

See also: setFile()

◆ setUseLock()

void Wt::WLogger::setUseLock ( bool enable )

Enabled the logger to take locks when logging.

This enables log entries to be consistently placed on their own line, upon a log() taking place. Without this functionality, it is possible that multiple entries can be put on the same line, followed by an empty line.

By default, this is enabled.

Note: For applications running in a dedicated process mode this may not be sufficient.

◆ useLock()

bool Wt::WLogger::useLock ( ) const

Returns whether the logger use a mutex.

See also: setUseLock()

Friends And Related Function Documentation

◆ log()

WLogEntry log ( const std::string & type )

This creates a new log entry, e.g.:

Wt::log("info") << "Doing something interesting now with " << appleCount() << " apples.";

Member Data Documentation

◆ sep

const WLogger::Sep Wt::WLogger::sep = WLogger::Sep()

static

Field separator constant.

See also: WLogEntry::operator<<(const WLogger::Sep&)

◆ timestamp

const WLogger::TimeStamp Wt::WLogger::timestamp = WLogger::TimeStamp()