Overview

Kea logging uses the concepts of the widely-used Java logging package log4j (https://logging.apache.org/log4j/), albeit implemented in C++ using an open-source port. Features of the system are:

Within the code objects - known as loggers - can be created and used to log messages. These loggers have names; those with the same name share characteristics (such as output destination).
Loggers have a hierarchical relationship, with each logger being the child of another logger, except for the top of the hierarchy, the root logger. If a logger does not log a message, it is passed to the parent logger.
Messages can be logged at severity levels of FATAL, ERROR, WARN, INFO or DEBUG. The DEBUG level has further sub-levels numbered 0 (least informative) to 99 (most informative).
Each logger has a severity level set associated with it. When a message is logged, it is output only if it is logged at a level equal to the logger severity level or greater, e.g. if the logger's severity is WARN, only messages logged at WARN, ERROR or FATAL will be output.

Kea Logger Names

Within Kea, the root logger root logger is given the name of the program (via the stand-alone function setRootLoggerName()). Other loggers are children of the root logger and are named "<program>.<sublogger>". This name appears in logging output, allowing users to identify both the Kea program and the component within the program that generated the message.

When creating a logger, the abbreviated name "<sublogger>" can be used; the program name will be prepended to it when the logger is created. In this way, individual libraries can have their own loggers without worrying about the program in which they are used, but:

The origin of the message will be clearly identified.
The same component can have different options (e.g. logging severity) in different programs at the same time.

Logging Messages

Instead of embedding the text of messages within the code, each message is referred to using a symbolic name. The logging code uses this name as a key in a dictionary from which the message text is obtained. Such a system allows for the optional replacement of message text at run time. More details about the message dictionary (and the compiler used to create the symbol definitions) can be found in other modules in the src/lib/log directory.

Implementation Issues

Owing to the way that the logging is implemented, notably that loggers can be declared as static external objects, there is a restriction on the length of the name of a logger component (i.e. the length of the string passed to the Logger constructor) to a maximum of 31 characters. There is no reason for this particular value other than limiting the amount of memory used. It is defined by the constant Logger::MAX_LOGGER_NAME_SIZE, and can be made larger (or smaller) if so desired.