From: Tomek Mrugalski Date: Tue, 16 Sep 2014 17:55:49 +0000 (+0200) Subject: [3536] Logging section in User's Guide updated. X-Git-Tag: rt3470_base~14^2~6 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=28811b7fe96516207847c74cbc8c94fff627f0ac;p=thirdparty%2Fkea.git [3536] Logging section in User's Guide updated. --- diff --git a/doc/guide/logging.xml b/doc/guide/logging.xml index 8d4427ada4..d740f035ff 100644 --- a/doc/guide/logging.xml +++ b/doc/guide/logging.xml @@ -11,92 +11,84 @@ 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. 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 module. All modules will look at the - configuration in Logging to see what should be logged and - to where. - - - + Logging module. All modules will look at the + configuration in Logging to see what should + be logged and to where. This allows sharing identical logging + configuration between components.
Loggers - Within Kea, a message is logged through a component called a "logger". Different parts of log messages through different loggers, and each logger can be configured independently of one another. - - In the Logging module, you can specify the configuration for zero or more loggers; any that are not specified will take appropriate default values. - - 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 using it to log messages. For instance, - if you want to configure logging for the Dhcp4 module, - you add an entry for a logger named Dhcp4. This - configuration will then be used by the loggers in the - Dhcp4 module, and all the libraries used by it (unless - a library defines its own logger). + 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 Dhcp4 module, you add an entry for + a logger named kea-dhcp4. This configuration will + then be used by the loggers in the Dhcp4 module, and all the + libraries used by it (unless a library defines its own logger). - -Right now you can only see what their names are if they are running -(a simple 'help' without anything else in bindctl for instance). - - --> + If you want to specify logging for one specific library within the + module, you set the name to + module.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 module. + - If you want to specify logging for one specific library - within the module, you set the name to - module.library. For example, the - logger used by the nameserver address store component - has the full name of Dhcp4.dhcpsrv. If - there is no entry in Logging for a particular library, - it will use the configuration given for the module. - - - - - To illustrate this, suppose you want the dhcpsrv library - to log messages of severity DEBUG, and the rest of the - Dhcp4 code to log messages of severity INFO. To achieve - this you specify two loggers, one with the name - Dhcp4 and severity INFO, and one with - the name Dhcp4.dhcpsrv with severity - DEBUG. As there are no entries for other libraries, - they will use the configuration for the module - (Dhcp4), so giving the desired behavior. - - + + To illustrate this, suppose you want the dhcpsrv library + to log messages of severity DEBUG, and the rest of the + Dhcp4 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 module + (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 * and Dhcp4, the - Dhcp4 module — and all libraries it uses — - will log messages according to the configuration in the - second entry (Dhcp4). All other modules - will use the configuration of the first entry - (*). - - - - + + 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 Dhcp4 module — 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 - module name within a logger, use the name of the binary file, - e.g. kea-dhcp4 for the DHCPv4 module, - kea-dhcp6 for the DHCPv6 module, etc. When - the message is logged, the message will include the name - of the logger generating the message, but with the module - name replaced by the name of the process implementing - the module (so for example, a message generated by the - DHCPv4 logger will appear in the output - with a logger name of kea-dhcp4). + + One final note about the naming. When specifying the module name + within a logger, use the name of the binary file, + e.g. kea-dhcp4 for the DHCPv4 module, + kea-dhcp6 for the DHCPv6 module, 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: + - - Currently defined loggers are: - kea-dhcp4.dhcp4 - kea-dhcp6.dhcp6 + kea-dhcp4.dhcpsrv - kea-dhcp-ddns.dhcpddns + kea-dhcp4.hooks - kea-dhcp4.dhcpsrv + kea-dhcp6.dhcp6 kea-dhcp6.dhcpsrv + + kea-dhcp6.hooks + + + kea-dhcp-ddns.dhcpddns + - Additional loggers may be defined in the future. + 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 @@ -448,7 +444,7 @@ file be created.
-
+
Logging Message Format @@ -499,7 +495,8 @@ file be created. case, kea-dhcp4) and the module within the program from which the message originated (which is the name of the common library used by DHCP server - implementations). + implementations). The number after the slash is a process id + (pid).