[3536] Logging section in User's Guide updated.

doc/guide/logging.xml

@@ -11,92 +11,84 @@
       <title>Logging configuration</title>
 
       <para>
+        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.
+      </para>
 
+      <para>
         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.
-
-<!-- TODO: what is context of Logging module for readers of this guide? -->
-
+        <replaceable>Logging</replaceable> module. All modules will look at the
+        configuration in <replaceable>Logging</replaceable> to see what should
+        be logged and to where. This allows sharing identical logging
+        configuration between components.
       </para>
 
       <section>
         <title>Loggers</title>
 
         <para>
-
           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.
-
         </para>
 
         <para>
-
           In the Logging module, you can specify the configuration
           for zero or more loggers; any that are not specified will
           take appropriate default values.
-
         </para>
 
         <para>
-
           The three most important elements of a logger configuration
           are the <option>name</option> (the component that is
           generating the messages), the <option>severity</option>
           (what to log), and the <option>output_options</option>
           (where to log).
-
         </para>
 
         <section>
           <title>name (string)</title>
 
           <para>
-            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 <quote>Dhcp4</quote>. 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 <quote>kea-dhcp4</quote>. 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).
           </para>
 
-<!-- TODO: later we will have a way to know names of all modules
+<!-- TODO: later we will have a way to know names of all modules -->
 
-Right now you can only see what their names are if they are running
-(a simple 'help' without anything else in bindctl for instance).
-
- -->
           <para>
+            If you want to specify logging for one specific library within the
+            module, you set the name to
+            <replaceable>module.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 module.
+          </para>
 
-          If you want to specify logging for one specific library
-          within the module, you set the name to
-          <replaceable>module.library</replaceable>.  For example, the
-          logger used by the nameserver address store component
-          has the full name of <quote>Dhcp4.dhcpsrv</quote>. If
-          there is no entry in Logging for a particular library,
-          it will use the configuration given for the module.
-        </para>
-
-       <para>
-
-          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
-          <quote>Dhcp4</quote> and severity INFO, and one with
-          the name <quote>Dhcp4.dhcpsrv</quote> with severity
-          DEBUG. As there are no entries for other libraries,
-          they will use the configuration for the module
-          (<quote>Dhcp4</quote>), so giving the desired behavior.
-
-        </para>
+          <para>
+            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
+            <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 module
+            (<quote>kea-dhcp4</quote>), so giving the desired behavior.
+          </para>
 
+        <!--
         <para>
-
           One special case is that of a module name of <quote>*</quote>
           (asterisks), which is interpreted as <emphasis>any</emphasis>
           module. You can set global logging options by using this,
@@ -104,68 +96,72 @@ Right now you can only see what their names are if they are running
           that is used by multiple modules (e.g. <quote>*.config</quote>
           specifies the configuration library code in whatever
           module is using it).
+        </para> -->
 
-        </para>
-
-        <para>
-
-          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 <quote>*</quote> and <quote>Dhcp4</quote>, the
-          Dhcp4 module &mdash; and all libraries it uses &mdash;
-          will log messages according to the configuration in the
-          second entry (<quote>Dhcp4</quote>). All other modules
-          will use the configuration of the first entry
-          (<quote>*</quote>).
-
-        </para>
-
-        <para>
+          <para>
+            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 <quote>kea-dhcp4</quote> and
+            <quote>kea-dhcp4.dhcpsrv</quote>, the Dhcp4 module &mdash; and all
+            libraries it uses that are not dhcpsrv &mdash; will log messages
+            according to the configuration in the first entry
+            (<quote>kea-dhcp4</quote>).
+          </para>
 
-          One final note about the naming. When specifying the
-          module name within a logger, use the name of the binary file,
-          e.g. <quote>kea-dhcp4</quote> for the DHCPv4 module,
-          <quote>kea-dhcp6</quote> 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
-          <quote>DHCPv4</quote> logger will appear in the output
-          with a logger name of <quote>kea-dhcp4</quote>).
+          <para>
+            One final note about the naming. When specifying the module name
+            within a logger, use the name of the binary file,
+            e.g. <quote>kea-dhcp4</quote> for the DHCPv4 module,
+            <quote>kea-dhcp6</quote> for the DHCPv6 module, 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>
+          <para>
+            Currently defined loggers are:
+          </para>
 
-        <para>
-          Currently defined loggers are:
-        </para>
         <itemizedlist>
           <listitem>
             <simpara>kea-dhcp4.dhcp4</simpara>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp6.dhcp6</simpara>
+            <simpara>kea-dhcp4.dhcpsrv</simpara>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp-ddns.dhcpddns</simpara>
+            <simpara>kea-dhcp4.hooks</simpara>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp4.dhcpsrv</simpara>
+            <simpara>kea-dhcp6.dhcp6</simpara>
           </listitem>
           <listitem>
             <simpara>kea-dhcp6.dhcpsrv</simpara>
           </listitem>
+          <listitem>
+            <simpara>kea-dhcp6.hooks</simpara>
+          </listitem>
+          <listitem>
+            <simpara>kea-dhcp-ddns.dhcpddns</simpara>
+          </listitem>
         </itemizedlist>
 
-        <para>Additional loggers may be defined in the future.</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
+        <xref linkend="logging-message-format"/> for details.</para>
         </section>
 
         <section>
           <title>severity (string)</title>
 
         <para>
-
           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.</para>
 
     </section>
 
-    <section>
+    <section id="logging-message-format">
       <title>Logging Message Format</title>
 
       <para>
@@ -499,7 +495,8 @@ file be created.</para>
             case, <command>kea-dhcp4</command>) 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).
           </para></listitem>
           </varlistentry>