From: Marcin Siodelski <marcin@isc.org>
Date: Thu, 11 Jun 2015 07:47:26 +0000 (+0200)
Subject: [3805] Updated logging section in the User Guide.
X-Git-Tag: trac3732a_base~7^2~3
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=ac3ad577f66670f03e1f9554282592d2f7d1207f;p=thirdparty%2Fkea.git

[3805] Updated logging section in the User Guide.
---

diff --git a/doc/guide/logging.xml b/doc/guide/logging.xml
index 7ad2dac906..e1eb444f39 100644
--- a/doc/guide/logging.xml
+++ b/doc/guide/logging.xml
@@ -45,18 +45,35 @@
         <title>Loggers</title>
 
         <para>
-          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).
+          Within Kea, a message is logged through an entity called a
+          "logger". Different components log messages through different
+          loggers, and each logger can be configured independently of
+          one another. Some components, in particular DHCP server
+          processes, may use multiple loggers to log messages pertaining
+          to different logical functions of the component. For example,
+          the DHCPv4 server is using different logger for messages
+          pertaining to packet reception and transmission, another
+          logger for messages related to lease allocation and so on.
+          Some of the libraries used by the Kea servers, e.g. libdhcpsrv
+          or libhooks library, use their own loggers.
         </para>
 
         <para>
-          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
+          Users implementing hooks libraries, attached to the server at
+          runtime, are responsible for creating loggers exclusively used
+          by those libraries. Such loggers are configured independently
+          from other loggers and should have unique names to allow for
+          distingushing messages emitted from the hook library from
+          messages emitted by the core Kea code. Whenever it makes sense,
+          hook library can use multiple loggers to log messages pertaining
+          to different logical parts of the library.
+        </para>
+
+        <para>
+          In the <quote>Logging</quote> structure of a configuration file
+          you can specify the configuration for zero or more loggers
+          (including loggers used by the proprietary hooks libraries). 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.
           <!-- @todo: add reference to section about controlling default
@@ -85,7 +102,7 @@
           </para>
 
           <para>
-            When diagnosing the problem with the server's operation it is often
+            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
@@ -323,6 +340,28 @@
 
         </itemizedlist>
 
+        <para>
+          Note that user defined hook libraries should not use any of those
+          loggers, and should define new loggers with names that correspond to
+          the libraries using them. Suppose that the user created the library called
+          <quote>libpacket-capture</quote> to dump packets received and
+          transmitted by the server to the file. The appropriate name for the
+          logger could be <command>kea-dhcp4.packet-capture</command>. Note
+          that the hook library implementor only specifies the second part
+          of this name, i.e. <quote>packet-capture</quote>. The first part is
+          a root logger name and is prepended by the Kea logging system.
+          It is also important to note that since this new logger is a child
+          of a root logger, it inherits the configuration from the root logger,
+          unless there is a separate configuration entry for the child logger
+          which overrides the default configuration.
+        </para>
+
+        <para>
+          The list of loggers above excludes any loggers implemented in hooks
+          libraries. Please consult the documentation of the specific hooks
+          libraries for the names of loggers they define!
+        </para>
+
         <para>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