[3806] Updated Logging section in the user guide.

Listed all loggers and updated the introductory text.

doc/guide/logging.xml

@@ -85,25 +85,46 @@
           </para>
 
           <para>
-            If you want to specify logging for one specific library within a
-            daemon, you set the name to
-            <replaceable>daemon.library</replaceable>.  For example, the logger
-            used by the code from libdhcpsrv used in kea-dhcp4 binary has the
-            full name of <quote>kea-dhcp4.dhcpsrv</quote>. 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.
           </para>
 
           <para>
-            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
-            <quote>kea-dhcp4</quote> and severity INFO, and one with
-            the name <quote>kea-dhcp4.dhcpsrv</quote> with severity
-            DEBUG. As there are no entries for other libraries,
-            they will use the configuration for the daemon
-            (<quote>kea-dhcp4</quote>), 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.
+          </para>
+
+          <para>
+            To illustrate this, suppose you are using the DHCPv4 server
+            with the root logger <quote>kea-dhcp4</quote> 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 <quote>kea-dhcp4.bad_packet</quote> 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.
           </para>
 
         <!-- we don't support asterisk anymore.
@@ -129,21 +150,6 @@
           </para>
 
           <para>
-            One final note about the naming. When specifying the daemon name
-            within a logger, use the name of the binary file,
-            e.g. <quote>kea-dhcp4</quote> for the DHCPv4 server,
-            <quote>kea-dhcp6</quote> for the DHCPv6 server, etc. When the
-            message is logged, the message will include the name of the process
-            (e.g. <quote>kea-dhcp4</quote>) followed by the specific component
-            in that process, e.g. <quote>hooks</quote>.  It is possible to
-            specify either just the process name (<quote>kea-dhcp4</quote>, will
-            apply to everything logged within that process) or process name
-            followed by specific logger,
-            e.g. <quote>kea-dhcp4.hooks</quote>. That will apply only to
-            messages originating from that component.
-          </para>
-
-          <para>
             Currently defined loggers are:
           </para>
 
@@ -158,7 +164,7 @@
             <simpara><command>kea-dhcp4.bad_packet</command> - this is the
             logger used by the DHCPv4 server deamon for logging inbound client
             packets that were dropped or to which the server responded with a
-            NAK.  The allows adminstrators to configure a separate log
+            DHCPNAK. The allows adminstrators to configure a separate log
             output that contains only packet drop and reject entries.</simpara>
           </listitem>
           <listitem>
@@ -174,8 +180,18 @@
           </listitem>
           <listitem>
             <simpara><command>kea-dhcp4.hooks</command> - this logger is used
-            during DHCPv4 hooks operation, i.e. anything related to user
-            libraries will be logged using this logger.</simpara>
+            by the hooks framework to log messages related to the execution of
+            callouts for various hook points. This logger doesn't log messages
+            which pertain to actions on the server side being the result of
+            the callout execution, e.g. skipping packet parsing by the server
+            because the callout has indicated that it has parsed the packet
+            already.</simpara>
+          </listitem>
+          <listitem>
+            <simpara><command>kea-dhcp4.hostname</command> - this logger is
+            used by the DHCPv4 server to log messages related to the Client
+            FQDN and Hostname option processing. It also includes log messages
+            related to the relevant DNS updates.</simpara>
           </listitem>
           <listitem>
             <simpara><command>kea-dhcp4.hosts</command> - this logger is used
@@ -184,6 +200,42 @@
             and adding new reservations.</simpara>
           </listitem>
           <listitem>
+            <simpara><command>kea-dhcp4.lease</command> - this logger is used
+            by the DHCPv4 server to log messages related to the lease allocation.
+            These messages are logged for each processed packet. The messages
+            include detailed information about the allocated or offered leases,
+            errors during the lease allocation etc.
+            </simpara>
+          </listitem>
+          <listitem>
+            <simpara><command>kea-dhcp4.options</command> - this logger is
+            used by the DHCPv4 server to log messages related to processing
+            of the options in the DHCPv4 messages, i.e. parsing options,
+            encoding options into on-wire format and packet classification
+            using options contained in the received packets.</simpara>
+          </listitem>
+          <listitem>
+            <simpara><command>kea-dhcp4.packet</command> - this logger
+            is mostly used to log messages related to transmission of the DHCPv4
+            packets, i.e. packet reception and sending a response. Such messages
+            include the information about the source and destination IP addresses
+            and interfaces used to transmit packets. This logger is also used
+            to log messages related to subnet selection, as this selection is
+            usually based on the IP addresses and/or interface names, which can
+            be retrieved from the received packet, even before the DHCPv4 message
+            carried in the packet is parsed.
+            </simpara>
+          </listitem>
+          <listitem>
+            <simpara><command>kea-dhcp4.server-hook</command> - this logger is
+            used by the DHCPv4 server to log messages pertaining to the
+            preparations for the callouts execution by the server and to the
+            actions taken by the server as a result of the callouts execution.
+            Note that it is a different logger than the
+            <command>kea-dhcp4.hooks</command> logger.
+          </simpara>
+          </listitem>
+          <listitem>
             <simpara><command>kea-dhcp6</command> - 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
@@ -202,8 +254,12 @@
           </listitem>
           <listitem>
             <simpara><command>kea-dhcp6.hooks</command> - this logger is used
-            during DHCPv6 hooks operation, i.e. anything related to user
-            libraries will be logged using this logger.</simpara>
+            by the hooks framework to log messages related to the execution of
+            callouts for various hook points. This logger doesn't log messages
+            which pertain to actions on the server side being the result of
+            the callout execution, e.g. skipping packet parsing by the server
+            because the callout has indicated that it has parsed the packet
+            already.</simpara>
           </listitem>
           <listitem>
             <simpara><command>kea-dhcp6.hosts</command> - this logger is used