From 21bb9fa77f7999ad4b64eb3245b38cd4927096cc Mon Sep 17 00:00:00 2001 From: Evan Hunt Date: Wed, 29 Jan 2020 15:24:43 -0800 Subject: [PATCH] improve documentation of query logging --- doc/arm/Bv9ARM-book.xml | 119 ++++++++++++++++++++++------------------ 1 file changed, 67 insertions(+), 52 deletions(-) diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml index 77445bd79e..0cc7831c3d 100644 --- a/doc/arm/Bv9ARM-book.xml +++ b/doc/arm/Bv9ARM-book.xml @@ -3964,69 +3964,64 @@ category notify { null; };
The <command>query-errors</command> Category The query-errors category is - specifically intended for debugging purposes: To identify - why and how specific queries result in responses which - indicate an error. - Messages of this category are therefore only logged - with debug levels. + used to indicate why and how specific queries resulted in + responses which indicate an error. Normally, these messages + will be logged at debug logging levels; + note, however, that if query logging is active, some will be + logged at info. The logging levels are + described below: - At the debug levels of 1 or higher, each response with the - rcode of SERVFAIL is logged as follows: + At debug level 1 or higher - or at + info, when query logging is active - each + response with response code SERVFAIL will be logged as follows: client 127.0.0.1#61502: query failed (SERVFAIL) for www.example.com/IN/AAAA at query.c:3880 - This means an error resulting in SERVFAIL was - detected at line 3880 of source file - query.c. - Log messages of this level will particularly - help identify the cause of SERVFAIL for an - authoritative server. + This means an error resulting in SERVFAIL was detected at line + 3880 of source file query.c. Log messages + of this level will particularly help identify the cause of + SERVFAIL for an authoritative server. - At the debug levels of 2 or higher, detailed context - information of recursive resolutions that resulted in - SERVFAIL is logged. - The log message will look like as follows: + At debug level 2 or higher, detailed + context information about recursive resolutions that resulted in + SERVFAIL will be logged. The log message will look like this: fetch completed at resolver.c:2970 for www.example.com/A -in 30.000183: timed out/success [domain:example.com, -referral:2,restart:7,qrysent:8,timeout:5,lame:0,neterr:0, +in 10.000183: timed out/success [domain:example.com, +referral:2,restart:7,qrysent:8,timeout:5,lame:0,quota:0,neterr:0, badresp:1,adberr:0,findfail:0,valfail:0] 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 resolver.c. The following part shows the detected final result and the - latest result of DNSSEC validation. - The latter is always success when no validation attempt - is made. - In this example, this query resulted in SERVFAIL probably - because all name servers are down or unreachable, leading - to a timeout in 30 seconds. - DNSSEC validation was probably not attempted. + latest result of DNSSEC validation. The latter is always + "success" when no validation attempt was made. In this example, + this query probably resulted in SERVFAIL because all name + servers are down or unreachable, leading to a timeout in 10 + seconds. DNSSEC validation was probably not attempted. - The last part enclosed in square brackets shows statistics - information collected for this particular resolution - attempt. - The domain field shows the deepest zone - that the resolver reached; - it is the zone where the error was finally detected. - The meaning of the other fields is summarized in the - following table. + The last part, enclosed in square brackets, shows statistics + collected for this particular resolution attempt. + The domain field shows the deepest zone that + the resolver reached; it is the zone where the error was + finally detected. The meaning of the other fields is + summarized in the following table. @@ -4100,6 +4095,18 @@ badresp:1,adberr:0,findfail:0,valfail:0] + + + quota + + + + The number of times the resolver was unable + to send a query because it had exceeded the + permissible fetch quota for a server. + + + neterr @@ -4170,20 +4177,17 @@ badresp:1,adberr:0,findfail:0,valfail:0] - At the debug levels of 3 or higher, the same messages - as those at the debug 1 level are logged for other errors - than SERVFAIL. - Note that negative responses such as NXDOMAIN are not - regarded as errors here. + At debug level 3 or higher, the same + messages as those at debug level 1 will be + logged for other errors than SERVFAIL. Note that negative + responses such as NXDOMAIN are not errors, and are not logged + at this debug level. - At the debug levels of 4 or higher, the same messages - as those at the debug 2 level are logged for other errors - than SERVFAIL. - Unlike the above case of level 3, messages are logged for - negative responses. - This is because any unexpected results can be difficult to - debug in the recursion case. + At debug level 4 or higher, the + detailed context information logged at debug + level 2 will be logged for other errors than SERVFAIL and + for negative resonses such as NXDOMAIN.
@@ -6531,11 +6535,22 @@ options { querylog - Specify whether query logging should be started when named - starts. - If querylog is not specified, - then the query logging - is determined by the presence of the logging category queries. + Query logging provides a complete log of all incoming + queries and all query errors. This provides more insight + into the server's activity, but with a cost to + performance which may be significant on heavily-loaded + servers. + + + The querylog option specifies + whether query logging should be active when + named first starts. + If querylog is not specified, then + query logging is determined by the presence of the + logging category queries. + Query logging can also be activated at runtime using the + command rndc querylog on, or + deactivated with rndc querylog off.