improve documentation of query logging

doc/arm/Bv9ARM-book.xml

@@ -3964,69 +3964,64 @@ category notify { null; };
 	<section xml:id="query_errors"><info><title>The <command>query-errors</command> Category</title></info>
 	  <para>
 	    The <command>query-errors</command> category is
-	    specifically intended for debugging purposes: To identify
+	    used to indicate why and how specific queries resulted in
-	    why and how specific queries result in responses which
+	    responses which indicate an error.  Normally, these messages
-	    indicate an error.
+	    will be logged at <command>debug</command> logging levels;
-	    Messages of this category are therefore only logged
+	    note, however, that if query logging is active, some will be
-	    with <command>debug</command> levels.
+	    logged at <command>info</command>. The logging levels are
+	    described below:
 	  </para>
 
 	  <para>
-	    At the debug levels of 1 or higher, each response with the
+	    At <command>debug</command> level 1 or higher - or at
-	    rcode of SERVFAIL is logged as follows:
+	    <command>info</command>, when query logging is active - each
+	    response with response code SERVFAIL will be logged as follows:
 	  </para>
 	  <para>
 	    <computeroutput>client 127.0.0.1#61502: query failed (SERVFAIL) for www.example.com/IN/AAAA at query.c:3880</computeroutput>
 	  </para>
 	  <para>
-	    This means an error resulting in SERVFAIL was
+	    This means an error resulting in SERVFAIL was detected at line
-	    detected at line 3880 of source file
+	    3880 of source file <filename>query.c</filename>.  Log messages
-	    <filename>query.c</filename>.
+	    of this level will particularly help identify the cause of
-	    Log messages of this level will particularly
+	    SERVFAIL for an authoritative server.
-	    help identify the cause of SERVFAIL for an
-	    authoritative server.
 	  </para>
 	  <para>
-	    At the debug levels of 2 or higher, detailed context
+	    At <command>debug</command> level 2 or higher, detailed
-	    information of recursive resolutions that resulted in
+	    context information about recursive resolutions that resulted in
-	    SERVFAIL is logged.
+	    SERVFAIL will be logged.  The log message will look like this:
-	    The log message will look like as follows:
 	  </para>
 	  <para>
 <!-- NOTE: newlines and some spaces added so this would fit on page -->
 	    <programlisting>
 fetch completed at resolver.c:2970 for www.example.com/A
-in 30.000183: timed out/success [domain:example.com,
+in 10.000183: timed out/success [domain:example.com,
-referral:2,restart:7,qrysent:8,timeout:5,lame:0,neterr:0,
+referral:2,restart:7,qrysent:8,timeout:5,lame:0,quota:0,neterr:0,
 badresp:1,adberr:0,findfail:0,valfail:0]
 	    </programlisting>
 	  </para>
 	  <para>
 	    The first part before the colon shows that a recursive
 	    resolution for AAAA records of www.example.com completed
-	    in 30.000183 seconds and the final result that led to the
+	    in 10.000183 seconds and the final result that led to the
 	    SERVFAIL was determined at line 2970 of source file
 	    <filename>resolver.c</filename>.
 	  </para>
 	  <para>
 	    The following part shows the detected final result and the
-	    latest result of DNSSEC validation.
+	    latest result of DNSSEC validation.  The latter is always
-	    The latter is always success when no validation attempt
+	    "success" when no validation attempt was made.  In this example,
-	    is made.
+	    this query probably resulted in SERVFAIL because all name
-	    In this example, this query resulted in SERVFAIL probably
+	    servers are down or unreachable, leading to a timeout in 10
-	    because all name servers are down or unreachable, leading
+	    seconds.  DNSSEC validation was probably not attempted.
-	    to a timeout in 30 seconds.
-	    DNSSEC validation was probably not attempted.
 	  </para>
 	  <para>
-	    The last part enclosed in square brackets shows statistics
+	    The last part, enclosed in square brackets, shows statistics
-	    information collected for this particular resolution
+	    collected for this particular resolution attempt.
-	    attempt.
+	    The <varname>domain</varname> field shows the deepest zone that
-	    The <varname>domain</varname> field shows the deepest zone
+	    the resolver reached; it is the zone where the error was
-	    that the resolver reached;
+	    finally detected.  The meaning of the other fields is
-	    it is the zone where the error was finally detected.
+	    summarized in the following table.
-	    The meaning of the other fields is summarized in the
-	    following table.
 	  </para>
 
 	  <informaltable colsep="0" rowsep="0">
@@ -4100,6 +4095,18 @@ badresp:1,adberr:0,findfail:0,valfail:0]
 		    </para>
 		  </entry>
 		</row>
+		<row rowsep="0">
+		  <entry colname="1">
+		    <para><varname>quota</varname></para>
+		  </entry>
+		  <entry colname="2">
+		    <para>
+		      The number of times the resolver was unable
+		      to send a query because it had exceeded the
+		      permissible fetch quota for a server.
+		    </para>
+		  </entry>
+		</row>
 		<row rowsep="0">
 		  <entry colname="1">
 		    <para><varname>neterr</varname></para>
@@ -4170,20 +4177,17 @@ badresp:1,adberr:0,findfail:0,valfail:0]
 	    </tgroup>
 	  </informaltable>
 	  <para>
-	    At the debug levels of 3 or higher, the same messages
+	    At <command>debug</command> level 3 or higher, the same
-	    as those at the debug 1 level are logged for other errors
+	    messages as those at <command>debug</command> level 1 will be
-	    than SERVFAIL.
+	    logged for other errors than SERVFAIL. Note that negative
-	    Note that negative responses such as NXDOMAIN are not
+	    responses such as NXDOMAIN are not errors, and are not logged
-	    regarded as errors here.
+	    at this debug level.
 	  </para>
 	  <para>
-	    At the debug levels of 4 or higher, the same messages
+	    At <command>debug</command> level 4 or higher, the
-	    as those at the debug 2 level are logged for other errors
+	    detailed context information logged at <command>debug</command>
-	    than SERVFAIL.
+	    level 2 will be logged for other errors than SERVFAIL and
-	    Unlike the above case of level 3, messages are logged for
+	    for negative resonses such as NXDOMAIN.
-	    negative responses.
-	    This is because any unexpected results can be difficult to
-	    debug in the recursion case.
 	  </para>
 	</section>
       </section>
@@ -6531,11 +6535,22 @@ options {
 	      <term><command>querylog</command></term>
 	      <listitem>
 		<para>
-		  Specify whether query logging should be started when <command>named</command>
+		  Query logging provides a complete log of all incoming
-		  starts.
+		  queries and all query errors. This provides more insight
-		  If <command>querylog</command> is not specified,
+		  into the server's activity, but with a cost to
-		  then the query logging
+		  performance which may be significant on heavily-loaded
-		  is determined by the presence of the logging category <command>queries</command>.
+		  servers.
+		</para>
+		<para>
+		  The <command>querylog</command> option specifies
+		  whether query logging should be active when
+		  <command>named</command> first starts.
+		  If <command>querylog</command> is not specified, then
+		  query logging is determined by the presence of the
+		  logging category <command>queries</command>.
+		  Query logging can also be activated at runtime using the
+		  command <command>rndc querylog on</command>, or
+		  deactivated with <command>rndc querylog off</command>.
 		</para>
 	      </listitem>
 	    </varlistentry>