[3427] User's Guide updated

doc/guide/logging.xml

@@ -126,7 +126,7 @@ Right now you can only see what their names are if they are running
 
           One final note about the naming. When specifying the
           module name within a logger, use the name of the module
-          as specified in <command>bindctl</command>, e.g.
+          as specified in JSON configuration, e.g.
           <quote>Dhcp4</quote> for the Dhcp4 module,
           <quote>Dhcp6</quote> for the Dhcp6 module, etc. When
           the message is logged, the message will include the name
@@ -297,65 +297,22 @@ TODO; there's a ticket to determine these levels, see #1074
           <title>output (string)</title>
 
         <para>
-
-          Depending on what is set as the output destination, this
-          value is interpreted as follows:
-
+          This value determines the type of output. There are several
+          special values allowed here: <command>stdout</command> (messages
+          are printed on standard output), <command>stderr</command>
+          (messages are printed on stderr), <command>syslog</command> (messages
+          are logged to syslog using default name, <command>syslog:name</command>
+          (messages are logged to syslog using specified name). Any other
+          value is interpreted as a filename that the logs should be written to.
         </para>
 
-        <variablelist>
-
-          <varlistentry>
-            <term><option>destination</option> is <quote>console</quote></term>
-            <listitem>
-              <para>
-                 The value of output must be one of <quote>stdout</quote>
-                 (messages printed to standard output) or
-                 <quote>stderr</quote> (messages printed to standard
-                 error).
-              </para>
-              <para>
-                Note: if output is set to <quote>stderr</quote> and a lot of
-                messages are produced in a short time (e.g. if the logging
-                level is set to DEBUG), you may occasionally see some messages
-                jumbled up together.  This is due to a combination of the way
-                that messages are written to the screen and the unbuffered
-                nature of the standard error stream.  If this occurs, it is
-                recommended that output be set to <quote>stdout</quote>.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term><option>destination</option> is <quote>file</quote></term>
-            <listitem>
-              <para>
-                The value of output is interpreted as a file name;
-                log messages will be appended to this file.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term><option>destination</option> is <quote>syslog</quote></term>
-            <listitem>
-              <para>
-                The value of output is interpreted as the
-                <command>syslog</command> facility (e.g.
-                <emphasis>local0</emphasis>) that should be used
-                for log messages.
-              </para>
-            </listitem>
-          </varlistentry>
-
-        </variablelist>
-
         <para>
 
           The other options for <option>output_options</option> are:
 
         </para>
 
+        <!-- configuration of flush is not supported yet. 
         <section>
           <title>flush (true of false)</title>
 
@@ -366,7 +323,7 @@ TODO; there's a ticket to determine these levels, see #1074
             termination are output.
           </para>
 
-        </section>
+        </section> -->
 
         <section>
           <title>maxsize (integer)</title>
@@ -409,7 +366,7 @@ TODO; there's a ticket to determine these levels, see #1074
           <para>
             Maximum number of old log files to keep around when
             rolling the output file. Only relevant when
-            <option>destination</option> is <quote>file</quote>.
+            <option>output</option> is <quote>file</quote>.
           </para>
 
         </section>
@@ -419,216 +376,53 @@ TODO; there's a ticket to determine these levels, see #1074
       </section>
 
       <section>
-        <title>Example session</title>
+        <title>Example Logger configurations</title>
 
         <para>
-
           In this example we want to set the global logging to
-          write to the file <filename>/var/log/my_bind10.log</filename>,
-          at severity WARN. We want the authoritative server to
-          log at DEBUG with debuglevel 40, to a different file
-          (<filename>/tmp/debug_messages</filename>).
-
-        </para>
-
-        <para>
-
-          Start <command>bindctl</command>.
-
-        </para>
-
-        <para>
-
-           <screen>["login success "]
-&gt; <userinput>config show Logging</userinput>
-Logging/loggers	[]	list
-</screen>
-
-        </para>
-
-        <para>
-
-          By default, no specific loggers are configured, in which
-          case the severity defaults to INFO and the output is
-          written to stderr.
-
-        </para>
-
-        <para>
-
-          Let's first add a default logger:
-
-        </para>
-
-<!-- TODO: adding the empty loggers makes no sense -->
-        <para>
-
-          <screen>&gt; <userinput>config add Logging/loggers</userinput>
-&gt; <userinput>config show Logging</userinput>
-Logging/loggers/	list	(modified)
-</screen>
-
-        </para>
-
-        <para>
-
-          The loggers value line changed to indicate that it is no
-          longer an empty list:
-
-        </para>
-
-        <para>
-
-          <screen>&gt; <userinput>config show Logging/loggers</userinput>
-Logging/loggers[0]/name	""	string	(default)
-Logging/loggers[0]/severity	"INFO"	string	(default)
-Logging/loggers[0]/debuglevel	0	integer	(default)
-Logging/loggers[0]/additive	false	boolean	(default)
-Logging/loggers[0]/output_options	[]	list	(default)
-</screen>
-
-        </para>
-
-        <para>
-
-          The name is mandatory, so we must set it. We will also
-          change the severity as well. Let's start with the global
-          logger.
-
-        </para>
-
-        <para>
-
-          <screen>&gt; <userinput>config set Logging/loggers[0]/name *</userinput>
-&gt; <userinput>config set Logging/loggers[0]/severity WARN</userinput>
-&gt; <userinput>config show Logging/loggers</userinput>
-Logging/loggers[0]/name	"*"	string	(modified)
-Logging/loggers[0]/severity	"WARN"	string	(modified)
-Logging/loggers[0]/debuglevel	0	integer	(default)
-Logging/loggers[0]/additive	false	boolean	(default)
-Logging/loggers[0]/output_options	[]	list	(default)
+          write to the console using standard output.
+        </para>
+
+<screen><userinput>
+"Logging": {
+    "loggers": [
+        {
+            "name": "*",
+            "output_options": [
+                {
+                    "output": "stdout"
+                }
+            ], 
+            "severity": "WARN"
+        }
+    ]
+}
+</userinput>
 </screen>
 
-        </para>
-
-        <para>
-
-          Of course, we need to specify where we want the log
-          messages to go, so we add an entry for an output option.
-
-        </para>
-
-        <para>
-
-          <screen>&gt; <userinput> config add Logging/loggers[0]/output_options</userinput>
-&gt; <userinput> config show Logging/loggers[0]/output_options</userinput>
-Logging/loggers[0]/output_options[0]/destination	"console"	string	(default)
-Logging/loggers[0]/output_options[0]/output	"stdout"	string	(default)
-Logging/loggers[0]/output_options[0]/flush	false	boolean	(default)
-Logging/loggers[0]/output_options[0]/maxsize	0	integer	(default)
-Logging/loggers[0]/output_options[0]/maxver	0	integer	(default)
-</screen>
-
-
-        </para>
-
-        <para>
-
-          These aren't the values we are looking for.
-
-        </para>
-
-        <para>
-
-          <screen>&gt; <userinput> config set Logging/loggers[0]/output_options[0]/destination file</userinput>
-&gt; <userinput> config set Logging/loggers[0]/output_options[0]/output /var/log/kea.log</userinput>
-&gt; <userinput> config set Logging/loggers[0]/output_options[0]/maxsize 204800</userinput>
-&gt; <userinput> config set Logging/loggers[0]/output_options[0]/maxver 8</userinput>
-</screen>
-
-        </para>
-
-        <para>
-
-          Which would make the entire configuration for this logger
-          look like:
-
-        </para>
-
-        <para>
-
-          <screen>&gt; <userinput> config show all Logging/loggers</userinput>
-Logging/loggers[0]/name	"*"	string	(modified)
-Logging/loggers[0]/severity	"WARN"	string	(modified)
-Logging/loggers[0]/debuglevel	0	integer	(default)
-Logging/loggers[0]/additive	false	boolean	(default)
-Logging/loggers[0]/output_options[0]/destination	"file"	string	(modified)
-Logging/loggers[0]/output_options[0]/output	"/var/log/kea.log"	string	(modified)
-Logging/loggers[0]/output_options[0]/flush	false	boolean	(default)
-Logging/loggers[0]/output_options[0]/maxsize	204800	integer	(modified)
-Logging/loggers[0]/output_options[0]/maxver	8	integer	(modified)
-</screen>
-
-        </para>
-
-        <para>
-
-          That looks OK, so let's commit it before we add the
-          configuration for the authoritative server's logger.
-
-        </para>
-
-        <para>
-
-          <screen>&gt; <userinput> config commit</userinput></screen>
-
-        </para>
-
-        <para>
-
-          Now that we have set it, and checked each value along
-          the way, adding a second entry is quite similar.
-
-        </para>
-
-        <para>
-
-          <screen>&gt; <userinput> config add Logging/loggers</userinput>
-&gt; <userinput> config set Logging/loggers[1]/name Dhcp4</userinput>
-&gt; <userinput> config set Logging/loggers[1]/severity DEBUG</userinput>
-&gt; <userinput> config set Logging/loggers[1]/debuglevel 40</userinput>
-&gt; <userinput> config add Logging/loggers[1]/output_options</userinput>
-&gt; <userinput> config set Logging/loggers[1]/output_options[0]/destination file</userinput>
-&gt; <userinput> config set Logging/loggers[1]/output_options[0]/output /tmp/dhcp4_debug.log</userinput>
-&gt; <userinput> config commit</userinput>
-</screen>
-
-        </para>
-
-        <para>
-
-          And that's it. Once we have found whatever it was we
-          needed the debug messages for, we can simply remove the
-          second logger to let the DHCP server use the
-          same settings as the rest.
-
-        </para>
-
-        <para>
-
-          <screen>&gt; <userinput> config remove Logging/loggers[1]</userinput>
-&gt; <userinput> config commit</userinput>
-</screen>
-
-        </para>
-
-        <para>
-
-          And every module will now be using the values from the
-          logger named <quote>*</quote>.
-
-        </para>
-
+<para>In this second example, we want to store debug log messages
+in a file that is at most 2MB and keep up to 8 copies of old logfiles.
+Once the logfile grows to 2MB, it will be renamed and a new file
+file be created.</para>
+
+<screen><userinput>
+"Logging": {
+    "loggers": [
+        {
+            "name": "kea",
+            "output_options": [
+                {
+                    "output": "/var/log/kea-debug.log",
+                    "maxver": 8,
+                    "maxsize": 204800,
+                    "destination": "file"
+                }
+            ], 
+            "severity": "DEBUG",
+            "debuglevel": 99
+        }
+   ]
+}</userinput></screen>
       </section>
 
     </section>