Logging

Logging Configuration During its operation Kea may produce many messages. They differ in severity (some are more important than others) and source (some are produced by specific components, e.g. hooks). It is useful to understand which log messages are needed and which are not and configure your logging appropriately. For example, debug level messages can be safely ignored in a typical deployment. They are, however, very useful when debugging a problem. The logging system in Kea is configured through the Logging structure in your configuration file. All daemons (e.g. DHCPv4 and DHCPv6 servers) will use the configuration in the Logging structure to see what should be logged and to where. This allows for sharing identical logging configuration between daemons.

Loggers Within Kea, a message is logged through an entity called a "logger". Different parts of the code log messages through different loggers, and each logger can be configured independently of one another. For example there are different components that deal with hooks ("hooks" logger) and with DHCP engine ("dhcpsrv" logger). In the Logging structure in a configuration file you can specify the configuration for zero or more loggers. If there are no loggers specified, the code will use default values which cause Kea to log messages on at least INFO severity to standard output. The three most important elements of a logger configuration are the (the component that is generating the messages), the (what to log), and the (where to log).

name (string) Each logger in the system has a name, the name being that of the component binary file using it to log messages. For instance, if you want to configure logging for the DHCPv4 server, you add an entry for a logger named kea-dhcp4. This configuration will then be used by the loggers in the DHCPv4 server, and all the libraries used by it (unless a library defines its own logger and there is specific logger configuration that applies to that logger). If you want to specify logging for one specific library within a daemon, you set the name to daemon.library. For example, the logger used by the code from libdhcpsrv used in kea-dhcp4 binary has the full name of kea-dhcp4.dhcpsrv. If there is no entry in Logging for a particular library, it will use the configuration given for the whole daemon. To illustrate this, suppose you want the dhcpsrv library to log messages of severity DEBUG, and the rest of the DHCPv4 server code to log messages of severity INFO. To achieve this you specify two loggers, one with the name kea-dhcp4 and severity INFO, and one with the name kea-dhcp4.dhcpsrv with severity DEBUG. As there are no entries for other libraries, they will use the configuration for the daemon (kea-dhcp4), so giving the desired behavior. If there are multiple logger specifications in the configuration that might match a particular logger, the specification with the more specific logger name takes precedence. For example, if there are entries for both kea-dhcp4 and kea-dhcp4.dhcpsrv, the DHCPv4 server — and all libraries it uses that are not dhcpsrv — will log messages according to the configuration in the first entry (kea-dhcp4). One final note about the naming. When specifying the daemon name within a logger, use the name of the binary file, e.g. kea-dhcp4 for the DHCPv4 server, kea-dhcp6 for the DHCPv6 server, etc. When the message is logged, the message will include the name of the process (e.g. kea-dhcp4) followed by the specific component in that process, e.g. hooks. It is possible to specify either just the process name (kea-dhcp4, will apply to everything logged within that process) or process name followed by specific logger, e.g. kea-dhcp4.hooks. That will apply only to messages originating from that component. Currently defined loggers are: kea-dhcp4 - this is the root logger for the DHCPv4 server. All components used by the DHCPv4 server inherit the settings from this logger if there is no specialized logger provided. kea-dhcp4.dhcp4 - this is the logger used solely by the DHCPv4 server deamon. This logger does not specify logging settings for libraries used by the deamon. kea-dhcp4.dhcpsrv - this logger is used by the libdhcpsrv library. This covers mostly DHCP engine (the lease allocation and renewal process), database operations and configuration. kea-dhcp4.hooks - this logger is used during DHCPv4 hooks operation, i.e. anything related to user libraries will be logged using this logger. kea-dhcp6 - this is the root logger for the DHCPv6 server. All components used by the DHCPv6 server inherit the settings from this logger if there is no specialized logger provided. kea-dhcp6.dhcp6 - this is the logger used solely by the DHCPv6 server deamon. This logger does not specify logging settings for libraries used by the daemon. kea-dhcp6.dhcpsrv - this logger is used by the libdhcpsrv library. This covers mostly DHCP engine (the lease allocation and renewal process), database operations and configuration. kea-dhcp6.hooks - this logger is used during DHCPv6 hooks operation, i.e. anything related to user libraries will be logged using this logger. kea-dhcp-ddns - this is the root logger for the kea-dhcp-ddns deamon. All components used by this deamon inherit the settings from this logger if there is no specialized logger provided. kea-dhcp-ddns.dhcpddns - this is the logger used solely by the kea-dhcp-ddns deamon. This logger does not specify logging settings for libraries used by the deamon. Additional loggers may be defined in the future. The easiest way to find out the logger name is to configure all logging to go to a single destination and look for specific logger names. See for details.

severity (string) This specifies the category of messages logged. Each message is logged with an associated severity which may be one of the following (in descending order of severity): FATAL ERROR WARN INFO DEBUG When the severity of a logger is set to one of these values, it will only log messages of that severity, and the severities above it. The severity may also be set to NONE, in which case all messages from that logger are inhibited.

output_options (list) Each logger can have zero or more . These specify where log messages are sent. These are explained in detail below. The other options for a logger are:

debuglevel (integer) When a logger's severity is set to DEBUG, this value specifies what debug messages should be printed. It ranges from 0 (least verbose) to 99 (most verbose). If severity for the logger is not DEBUG, this value is ignored.

Output Options The main settings for an output option are the and a value called , the meaning of which depends on the destination that is set.

destination (string) The destination is the type of output. It can be one of: console file syslog

output (string) This value determines the type of output. There are several special values allowed here: stdout (messages are printed on standard output), stderr (messages are printed on stderr), syslog (messages are logged to syslog using default name, syslog:name (messages are logged to syslog using specified name). Any other value is interpreted as a filename that the logs should be written to. The other options for are:

maxsize (integer) Only relevant when destination is file, this is maximum file size of output files in bytes. When the maximum size is reached, the file is renamed and a new file opened. (For example, a ".1" is appended to the name — if a ".1" file exists, it is renamed ".2", etc.) If this is 0, no maximum file size is used. Due to a limitation of the underlying logging library (log4cplus), rolling over the log files (from ".1" to ".2", etc) may show odd results: There can be multiple small files at the timing of roll over. This can happen when multiple processes try to roll over the files simultaneously. Version 1.1.0 of log4cplus solved this problem, so if this or higher version of log4cplus is used to build Kea, it shouldn't happen. Even for older versions it is normally expected to happen rarely unless the log messages are produced very frequently by multiple different processes.

maxver (integer) Maximum number of old log files to keep around when rolling the output file. Only relevant when is file.

Example Logger Configurations In this example we want to set the global logging to write to the console using standard output. "Logging": { "loggers": [ { "name": "kea-dhcp4", "output_options": [ { "output": "stdout" } ], "severity": "WARN" } ] } In this second example, we want to store debug log messages in a file that is at most 2MB and keep up to 8 copies of old logfiles. Once the logfile grows to 2MB, it will be renamed and a new file file be created. "Logging": { "loggers": [ { "name": "kea-dhcp6", "output_options": [ { "output": "/var/log/kea-debug.log", "maxver": 8, "maxsize": 204800, "destination": "file" } ], "severity": "DEBUG", "debuglevel": 99 } ] }