# Poco

# class Logger

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 not 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. Up to four arguments are supported.

Examples:

    poco_warning(logger, "This is a warning");
    poco_information_f2(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, 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

typedef std::map < std::string, Logger * > LoggerMap;

## Constructors

### Logger

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

## Destructor

### ~Logger

~Logger();

## Member Functions

### create

static Logger & create(
const std::string & name,
Channel * 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

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

bool critical() const;

Returns true if the log level is at least PRIO_CRITICAL.

### debug

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

bool debug() const;

Returns true if the log level is at least PRIO_DEBUG.

### destroy

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

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

bool error() const;

Returns true if the log level is at least PRIO_ERROR.

### fatal

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

bool fatal() const;

Returns true if the log level is at least PRIO_FATAL.

### format

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

Replaces all occurences 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 std::string format(
const std::string & fmt,
const std::string & arg0,
const std::string & arg1
);

Replaces all occurences 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 std::string format(
const std::string & fmt,
const std::string & arg0,
const std::string & arg1,
const std::string & arg2
);

Replaces all occurences 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 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 occurences 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 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 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 * getChannel() const;

Returns the Channel attached to the logger.

### getLevel

int getLevel() const;

Returns the Logger's log level.

### has

static Logger * has(
const std::string & name
);

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

### information

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

bool information() const;

Returns true if the log level is at least PRIO_INFORMATION.

### is

bool is(
int level
) const;

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

### log

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

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 void names(
std::vector < std::string > & names
);

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

### notice

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

bool notice() const;

Returns true if the log level is at least PRIO_NOTICE.

### parseLevel

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 Logger & root();

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

### setChannel

void setChannel(
Channel * pChannel
);

Attaches the given Channel to the Logger.

### setChannel

static void setChannel(
const std::string & name,
Channel * 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 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

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 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 void shutdown();

Shuts down the logging framework and releases all Loggers.

### trace

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

bool trace() const;

Returns true if the log level is at least PRIO_TRACE.

### unsafeGet

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

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

bool warning() const;

Returns true if the log level is at least PRIO_WARNING.

### add

static void add(
Logger * pLogger
);

### find

static Logger * find(
const std::string & name
);

### format

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

### log

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

### log

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

### parent

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

## Variables

### ROOT

static const std::string ROOT;

The name of the root logger ("").