Poco

class Logger

File Information

Library: Foundation
Package: Logging
Header: Poco/Logger.h

Description

Logger is a special Channel that acts as the main entry point into the logging framework.

An application uses instances of the Logger class to generate its log messages and send them on their way to their final destination. Logger instances are organized in a hierarchical, tree-like manner and are maintained by the framework. Every Logger object has exactly one direct ancestor, with the exception of the root logger. A newly created logger inherits its properties - channel and level - from its direct ancestor. Every logger is connected to a channel, to which it passes on its messages. Furthermore, every logger has a log level, which is used for filtering messages based on their priority. Only messages with a priority equal to or higher than the specified level are passed on. For example, if the level of a logger is set to three (PRIO_ERROR), only messages with priority PRIO_ERROR, PRIO_CRITICAL and PRIO_FATAL will propagate. If the level is set to zero, the logger is effectively disabled.

The name of a logger determines the logger's place within the logger hierarchy. The name of the root logger is always "", the empty string. For all other loggers, the name is made up of one or more components, separated by a period. For example, the loggers with the name HTTPServer.RequestHandler and HTTPServer.Listener are descendants of the logger HTTPServer, which itself is a descendant of the root logger. There is no limit as to how deep the logger hierarchy can become. Once a logger has been created and it has inherited the channel and level from its ancestor, it loses the connection to it. So, changes to the level or channel of a logger do not affect its descendants. This greatly simplifies the implementation of the framework and is no real restriction, because almost always levels and channels are set up at application startup and never changed afterwards. Nevertheless, there are methods to simultaneously change the level and channel of all loggers in a certain hierarchy.

There are also convenience macros available that wrap the actual logging statement into a check whether the Logger's log level is sufficient to actually log the message. This allows to increase the application performance if many complex log statements are used. The macros also add the source file path and line number into the log message so that it is available to formatters. Variants of these macros that allow message formatting with Poco::format() are also available.

Examples: 

poco_warning(logger, "This is a warning");
poco_information_f(logger, "An informational message with args: %d, %d", 1, 2);

Inheritance

Direct Base Classes: Channel

All Base Classes: Channel, Configurable, RefCountedObject

Member Summary

Member Functions: add, create, critical, debug, destroy, dump, error, fatal, find, format, formatDump, get, getChannel, getLevel, has, information, is, log, logNPC, name, names, notice, parent, parseLevel, root, setChannel, setLevel, setProperty, shutdown, trace, unsafeGet, warning

Inherited Functions: close, duplicate, getProperty, log, open, referenceCount, release, setProperty

Types

LoggerMap protected

typedef std::map < std::string, Ptr > LoggerMap;

Types Aliases

Ptr

using Ptr = AutoPtr < Logger >;

Constructors

Logger protected

Logger(
    const std::string & name,
    Channel::Ptr pChannel,
    int level
);

Destructor

~Logger protected virtual

~Logger();

Member Functions

create static

static Logger & create(
    const std::string & name,
    Channel::Ptr pChannel,
    int level = Message::PRIO_INFORMATION
);

Creates and returns a reference to a Logger with the given name. The Logger's Channel and log level as set as specified.

critical inline

void critical(
    const std::string & msg
);

If the Logger's log level is at least PRIO_CRITICAL, creates a Message with priority PRIO_CRITICAL and the given message text and sends it to the attached channel.

critical

void critical(
    const std::string & msg,
    const char * file,
    int line
);

If the Logger's log level is at least PRIO_CRITICAL, creates a Message with priority PRIO_CRITICAL and the given message text and sends it to the attached channel.

File must be a static string, such as the value of the __FILE__ macro. The string is not copied internally for performance reasons.

critical inline

template < typename T, typename ... Args > void critical(
    const std::string & fmt,
    T arg1,
    Args && ... args
);

critical

bool critical() const;

Returns true if the log level is at least PRIO_CRITICAL.

debug inline

void debug(
    const std::string & msg
);

If the Logger's log level is at least PRIO_DEBUG, creates a Message with priority PRIO_DEBUG and the given message text and sends it to the attached channel.

debug

void debug(
    const std::string & msg,
    const char * file,
    int line
);

If the Logger's log level is at least PRIO_DEBUG, creates a Message with priority PRIO_DEBUG and the given message text and sends it to the attached channel.

File must be a static string, such as the value of the __FILE__ macro. The string is not copied internally for performance reasons.

debug inline

template < typename T, typename ... Args > void debug(
    const std::string & fmt,
    T arg1,
    Args && ... args
);

debug

bool debug() const;

Returns true if the log level is at least PRIO_DEBUG.

destroy static

static void destroy(
    const std::string & name
);

Destroys the logger with the specified name. Does nothing if the logger is not found.

After a logger has been destroyed, all references to it become invalid.

dump

void dump(
    const std::string & msg,
    const void * buffer,
    std::size_t length,
    Message::Priority prio = Message::PRIO_DEBUG
);

Logs the given message, followed by the data in buffer.

The data in buffer is written in canonical hex+ASCII form: Offset (4 bytes) in hexadecimal, followed by sixteen space-separated, two column, hexadecimal bytes, followed by the same sixteen bytes as ASCII characters. For bytes outside the range 32 .. 127, a dot is printed.

error inline

void error(
    const std::string & msg
);

If the Logger's log level is at least PRIO_ERROR, creates a Message with priority PRIO_ERROR and the given message text and sends it to the attached channel.

error

void error(
    const std::string & msg,
    const char * file,
    int line
);

If the Logger's log level is at least PRIO_ERROR, creates a Message with priority PRIO_ERROR and the given message text and sends it to the attached channel.

File must be a static string, such as the value of the __FILE__ macro. The string is not copied internally for performance reasons.

error inline

template < typename T, typename ... Args > void error(
    const std::string & fmt,
    T arg1,
    Args && ... args
);

error

bool error() const;

Returns true if the log level is at least PRIO_ERROR.

fatal inline

void fatal(
    const std::string & msg
);

If the Logger's log level is at least PRIO_FATAL, creates a Message with priority PRIO_FATAL and the given message text and sends it to the attached channel.

fatal

void fatal(
    const std::string & msg,
    const char * file,
    int line
);

If the Logger's log level is at least PRIO_FATAL, creates a Message with priority PRIO_FATAL and the given message text and sends it to the attached channel.

File must be a static string, such as the value of the __FILE__ macro. The string is not copied internally for performance reasons.

fatal inline

template < typename T, typename ... Args > void fatal(
    const std::string & fmt,
    T arg1,
    Args && ... args
);

fatal

bool fatal() const;

Returns true if the log level is at least PRIO_FATAL.

format static

static std::string format(
    const std::string & fmt,
    const std::string & arg
);

Replaces all occurrences of $0 in fmt with the string given in arg and returns the result. To include a dollar sign in the result string, specify two dollar signs ($$) in the format string.

format static

static std::string format(
    const std::string & fmt,
    const std::string & arg0,
    const std::string & arg1
);

Replaces all occurrences of $<n> in fmt with the string given in arg<n> and returns the result. To include a dollar sign in the result string, specify two dollar signs ($$) in the format string.

format static

static std::string format(
    const std::string & fmt,
    const std::string & arg0,
    const std::string & arg1,
    const std::string & arg2
);

Replaces all occurrences of $<n> in fmt with the string given in arg<n> and returns the result. To include a dollar sign in the result string, specify two dollar signs ($$) in the format string.

format static

static std::string format(
    const std::string & fmt,
    const std::string & arg0,
    const std::string & arg1,
    const std::string & arg2,
    const std::string & arg3
);

Replaces all occurrences of $<n> in fmt with the string given in arg<n> and returns the result. To include a dollar sign in the result string, specify two dollar signs ($$) in the format string.

formatDump static

static void formatDump(
    std::string & message,
    const void * buffer,
    std::size_t length
);

Creates a hex-dump of the given buffer and appends it to the given message string.

get static

static Logger & get(
    const std::string & name
);

Returns a reference to the Logger with the given name. If the Logger does not yet exist, it is created, based on its parent logger.

getChannel

Channel::Ptr getChannel() const;

Returns the Channel attached to the logger.

getLevel inline

int getLevel() const;

Returns the Logger's log level.

has static

static Ptr has(
    const std::string & name
);

Returns a pointer to the Logger with the given name if it exists, or a null pointer otherwise.

information inline

void information(
    const std::string & msg
);

If the Logger's log level is at least PRIO_INFORMATION, creates a Message with priority PRIO_INFORMATION and the given message text and sends it to the attached channel.

information

void information(
    const std::string & msg,
    const char * file,
    int line
);

If the Logger's log level is at least PRIO_INFORMATION, creates a Message with priority PRIO_INFORMATION and the given message text and sends it to the attached channel.

File must be a static string, such as the value of the __FILE__ macro. The string is not copied internally for performance reasons.

information inline

template < typename T, typename ... Args > void information(
    const std::string & fmt,
    T arg1,
    Args && ... args
);

information

bool information() const;

Returns true if the log level is at least PRIO_INFORMATION.

is inline

bool is(
    int level
) const;

Returns true if at least the given log level is set.

log virtual inline

void log(
    const Message & msg
);

Logs the given message if its priority is greater than or equal to the Logger's log level.

See also: Poco::Channel::log()

log

void log(
    const Exception & exc
);

Logs the given exception with priority PRIO_ERROR.

log

void log(
    const Exception & exc,
    const char * file,
    int line
);

Logs the given exception with priority PRIO_ERROR.

File must be a static string, such as the value of the __FILE__ macro. The string is not copied internally for performance reasons.

name inline

const std::string & name() const;

Returns the name of the logger, which is set as the message source on all messages created by the logger.

names static

static void names(
    std::vector < std::string > & names
);

Fills the given vector with the names of all currently defined loggers.

notice inline

void notice(
    const std::string & msg
);

If the Logger's log level is at least PRIO_NOTICE, creates a Message with priority PRIO_NOTICE and the given message text and sends it to the attached channel.

notice

void notice(
    const std::string & msg,
    const char * file,
    int line
);

If the Logger's log level is at least PRIO_NOTICE, creates a Message with priority PRIO_NOTICE and the given message text and sends it to the attached channel.

File must be a static string, such as the value of the __FILE__ macro. The string is not copied internally for performance reasons.

notice inline

template < typename T, typename ... Args > void notice(
    const std::string & fmt,
    T arg1,
    Args && ... args
);

notice

bool notice() const;

Returns true if the log level is at least PRIO_NOTICE.

parseLevel static

static int parseLevel(
    const std::string & level
);

Parses a symbolic log level from a string and returns the resulting numeric level.

Valid symbolic levels are:

  • none (turns off logging)
  • fatal
  • critical
  • error
  • warning
  • notice
  • information
  • debug
  • trace

The level is not case sensitive.

root static

static Logger & root();

Returns a reference to the root logger, which is the ultimate ancestor of all Loggers.

setChannel

void setChannel(
    Channel::Ptr pChannel
);

Attaches the given Channel to the Logger.

setChannel static

static void setChannel(
    const std::string & name,
    Channel::Ptr pChannel
);

Attaches the given Channel to all loggers that are descendants of the Logger with the given name.

setLevel

void setLevel(
    int level
);

Sets the Logger's log level.

See Message::Priority for valid log levels. Setting the log level to zero turns off logging for that Logger.

setLevel

void setLevel(
    const std::string & level
);

Sets the Logger's log level using a symbolic value.

Valid values are:

  • none (turns off logging)
  • fatal
  • critical
  • error
  • warning
  • notice
  • information
  • debug
  • trace

setLevel static

static void setLevel(
    const std::string & name,
    int level
);

Sets the given log level on all loggers that are descendants of the Logger with the given name.

setProperty virtual

void setProperty(
    const std::string & name,
    const std::string & value
);

Sets or changes a configuration property.

Only the "channel" and "level" properties are supported, which allow setting the target channel and log level, respectively, via the LoggingRegistry. The "channel" and "level" properties are set-only.

See also: Poco::Channel::setProperty()

setProperty static

static void setProperty(
    const std::string & loggerName,
    const std::string & propertyName,
    const std::string & value
);

Sets or changes a configuration property for all loggers that are descendants of the Logger with the given name.

shutdown static

static void shutdown();

Shuts down the logging framework and releases all Loggers.

trace inline

void trace(
    const std::string & msg
);

If the Logger's log level is at least PRIO_TRACE, creates a Message with priority PRIO_TRACE and the given message text and sends it to the attached channel.

trace

void trace(
    const std::string & msg,
    const char * file,
    int line
);

If the Logger's log level is at least PRIO_TRACE, creates a Message with priority PRIO_TRACE and the given message text and sends it to the attached channel.

File must be a static string, such as the value of the __FILE__ macro. The string is not copied internally for performance reasons.

trace inline

template < typename T, typename ... Args > void trace(
    const std::string & fmt,
    T arg1,
    Args && ... args
);

trace

bool trace() const;

Returns true if the log level is at least PRIO_TRACE.

unsafeGet static

static Logger & unsafeGet(
    const std::string & name
);

Returns a reference to the Logger with the given name. If the Logger does not yet exist, it is created, based on its parent logger.

WARNING: This method is not thread safe. You should probably use get() instead. The only time this method should be used is during program initialization, when only one thread is running.

warning inline

void warning(
    const std::string & msg
);

If the Logger's log level is at least PRIO_WARNING, creates a Message with priority PRIO_WARNING and the given message text and sends it to the attached channel.

warning

void warning(
    const std::string & msg,
    const char * file,
    int line
);

If the Logger's log level is at least PRIO_WARNING, creates a Message with priority PRIO_WARNING and the given message text and sends it to the attached channel.

File must be a static string, such as the value of the __FILE__ macro. The string is not copied internally for performance reasons.

warning inline

template < typename T, typename ... Args > void warning(
    const std::string & fmt,
    T arg1,
    Args && ... args
);

warning

bool warning() const;

Returns true if the log level is at least PRIO_WARNING.

add protected static

static void add(
    Ptr pLogger
);

find protected static

static Ptr find(
    const std::string & name
);

format protected static

static std::string format(
    const std::string & fmt,
    int argc,
    std::string argv[]
);

log protected

void log(
    const std::string & text,
    Message::Priority prio
);

log protected

void log(
    const std::string & text,
    Message::Priority prio,
    const char * file,
    int line
);

logNPC protected inline

void logNPC(
    const std::string & text,
    Message::Priority prio
);

parent protected static

static Logger & parent(
    const std::string & name
);

Variables

ROOT static

static const std::string ROOT;

The name of the root logger ("").