From 5b779d6b844d38eef97fb3aadad2ed147b074646 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Thu, 7 May 2015 15:21:03 +0200 Subject: [PATCH] [3806] Updated Logging section in the user guide. Listed all loggers and updated the introductory text. --- doc/guide/logging.xml | 128 ++++++++++++++++++++++++++++++------------ 1 file changed, 92 insertions(+), 36 deletions(-) diff --git a/doc/guide/logging.xml b/doc/guide/logging.xml index 1283906a56..be48f70ae3 100644 --- a/doc/guide/logging.xml +++ b/doc/guide/logging.xml @@ -85,25 +85,46 @@ - 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. + When diagnosing the problem with the server's operation it is often + desired to use the DEBUG logging level to obtain the verbose output + from the server and libraries it uses. However, high verbosity may + be an overkill for the logging system in cases when the server + is processing high volume traffic. To mitigate this problem, Kea + is using multiple loggers, which can be configured independently + and which are responsible for logging messages from different + functional parts of the server. If the user, trying to diagnose the + problem, has a reasonably high confidence that the problem origins + in a specific function of the server, or the problem is related + to the specific type of operation, he may enable high verbosity + only for the relevant logger, thus limiting the debug messages + to the required minimum. - 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. + The loggers are associated with a particular library or binary + of Kea. However, each library or binary may (and usually does) + include multiple loggers. For example, the DHCPv4 server binary + contains separate loggers for: packet parsing, for dropped packets, + for callouts etc. Each logger "derives" its configuration from the + root logger. In the typical case, the root logger configuration + is the only logging configuration specified in the configuration + file. Creating a specific configuration for the selected logger, + thus overriding the configuration settings specified in the + root logger configuration, requires putting its configuration + aside of the root logger's configuration with some of the + parameters modified. + + + + To illustrate this, suppose you are using the DHCPv4 server + with the root logger kea-dhcp4 logging at the + INFO level. In order to enable DEBUG verbosity for the DHCPv4 + packet drops, you must create configuration entry for the + logger called kea-dhcp4.bad_packet and specify + severity DEBUG for this logger. All other configuration + parameters may be omited for this logger if the logger should + use the default values specified in the root logger's + configuration.