[3536] Changes after review:

 - Logging section updated.
 - Missing coma in kea.conf.pre added
 - ${localstatedir}/log is now created

Makefile.am

@@ -119,6 +119,10 @@ cppcheck:
 		--template '{file}:{line}: check_fail: {message} ({severity},{id})' \
 		src
 
+# These steps are necessary during installation
+install-exec-hook:
+	mkdir -p $(DESTDIR)${localstatedir}/log/
+
 ### include tool to generate documentation from log message specifications
 ### in the distributed tarball:
 EXTRA_DIST = tools/system_messages.py

doc/guide/logging.xml

@@ -4,6 +4,18 @@
 <!ENTITY mdash  "&#x2014;" >
 ]>
 
+  <!-- Note: Please use the following terminology:
+       - daemon - one process (e.g. kea-dhcp4)
+       - component - one piece of code within a daemon (e.g. libdhcp or hooks)
+       - server - currently equal to daemon, but the difference will be more
+                  prominent once we add client or relay support
+       - logger - one instance of isc::log::Logger
+       - structure - an element in config file (e.g. "Dhcp4")
+
+       Do not use:
+       - module => daemon
+    -->
+
   <chapter id="logging">
     <title>Logging</title>
 
@@ -14,33 +26,41 @@
         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.
+        which log messages are needed and which are not and configure your
+        logging appropriately. 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
-        <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.
+        <replaceable>Logging</replaceable> structure in your configuration
+        file. All daemons (e.g. a DHCPv4 and DHCPv6 servers) will look at the
+        configuration in the <replaceable>Logging</replaceable> structure to see
+        what should be logged and to where. This allows sharing identical
+        logging configuration between daemons.
       </para>
 
       <section>
         <title>Loggers</title>
 
         <para>
-          Within Kea, a message is logged through a component
-          called a "logger". Different parts of log messages
+          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.
+          independently of one another. For example there are different
+          components that deal with hooks ("hooks" logger) and with
+          DHCP engine ("dhcpsrv" logger).
         </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.
+          In the Logging structure in a configuration file you can
+          specify the configuration for zero or more loggers. If there are
+          no specified loggers, 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
+          behavior with env. variables, after #3591 is merged. -->
         </para>
 
         <para>
@@ -57,45 +77,44 @@
           <para>
             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).
+            want to configure logging for the DHCPv4 server, you add an entry
+            for a logger named <quote>kea-dhcp4</quote>. This configuration will
+            then be used by the loggers in the DHCPv4 server, and all the
+            libraries used by it (unless a library defines its own logger and
+            there is specific logger configuration that applies to that logger).
           </para>
 
-<!-- TODO: later we will have a way to know names of all modules -->
-
           <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
+            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 module.
+            given for the whole daemon.
           </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
+            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 module
+            they will use the configuration for the daemon
             (<quote>kea-dhcp4</quote>), so giving the desired behavior.
           </para>
 
-        <!--
+        <!-- we don't support asterisk anymore.
         <para>
-          One special case is that of a module name of <quote>*</quote>
+          One special case is that of a component name of <quote>*</quote>
           (asterisks), which is interpreted as <emphasis>any</emphasis>
-          module. You can set global logging options by using this,
+          component. You can set global logging options by using this,
           including setting the logging configuration for a library
-          that is used by multiple modules (e.g. <quote>*.config</quote>
+          that is used by multiple daemons (e.g. <quote>*.config</quote>
           specifies the configuration library code in whatever
-          module is using it).
+          daemon is using it).
         </para> -->
 
           <para>
@@ -103,17 +122,17 @@
             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
+            <quote>kea-dhcp4.dhcpsrv</quote>, the DHCPv4 server &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>
 
           <para>
-            One final note about the naming. When specifying the module name
+            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 module,
-            <quote>kea-dhcp6</quote> for the DHCPv6 module, etc. When the
+            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
@@ -130,25 +149,41 @@
 
         <itemizedlist>
           <listitem>
-            <simpara>kea-dhcp4.dhcp4</simpara>
+            <simpara><command>kea-dhcp4.dhcp4</command> - this is the logger
+            used by DHCPv4 server code in cases, where there is no more
+            specialized logger.</simpara>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp4.dhcpsrv</simpara>
+            <simpara><command>kea-dhcp4.dhcpsrv</command> - this logger is used
+            by the libdhcpsrv library. This covers mostly DHCP engine (the lease
+            allocation and renewal process), database operations and
+            configuration.</simpara>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp4.hooks</simpara>
+            <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>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp6.dhcp6</simpara>
+            <simpara><command>kea-dhcp6.dhcp6</command> - this logger is used
+            by DHCPv6 server code in cases, where there is no more specialzed
+            logger.</simpara>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp6.dhcpsrv</simpara>
+            <simpara><command>kea-dhcp6.dhcpsrv</command> - this logger is used
+            by the libdhcpsrv library. This covers mostly DHCP engine (the lease
+            allocation and renewal process), database operations and
+            configuration.</simpara>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp6.hooks</simpara>
+            <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>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp-ddns.dhcpddns</simpara>
+            <simpara><command>kea-dhcp-ddns.dhcpddns</command> - this is the
+            default logger for kea-dhcp-ddns daemon. This logger is not used
+            in DHCPv4 or DHCPv6 servers.</simpara>
           </listitem>
         </itemizedlist>
 
@@ -249,26 +284,6 @@ TODO; there's a ticket to determine these levels, see #1074
         </para>
 
         </section>
-
-        <section>
-          <title>additive (true or false)</title>
-
-        <para>
-
-          If this is true, the <option>output_options</option> from
-          the parent will be used. For example, if there are two
-          loggers configured; <quote>Dhcp4</quote> and
-          <quote>Dhcp4.dhcpsrv</quote>, and <option>additive</option>
-          is true in the second, it will write the log messages
-          not only to the destinations specified for
-          <quote>Dhcp4.dhcpsrv</quote>, but also to the destinations
-          as specified in the <option>output_options</option> in
-          the logger named <quote>Dhcp4</quote>.
-
-      </para>
-
-      </section>
-
       </section>
 
       <section>
@@ -490,9 +505,9 @@ file be created.</para>
           <varlistentry>
           <term>[kea-dhcp4.dhcpsrv/27456]</term>
           <listitem><para>
-            The source of the message.  This comprises two components:
+            The source of the message.  This comprises two elements:
             the Kea process generating the message (in this
-            case, <command>kea-dhcp4</command>) and the module
+            case, <command>kea-dhcp4</command>) and the component
             within the program from which the message originated
             (which is the name of the common library used by DHCP server
             implementations). The number after the slash is a process id

src/bin/keactrl/kea.conf.pre

@@ -92,7 +92,7 @@
       ],
       "severity": "INFO",
       "debuglevel": 0
-    }
+    },
     {
       "name": "kea-dhcp-ddns",
       "output_options": [