mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-30 14:07:59 +00:00
Code Issues Releases Wiki Activity

improve documentation of query logging

Browse Source
This commit is contained in:
Evan Hunt
2020-01-29 15:24:43 -08:00
parent e557894717
commit 21bb9fa77f
1 changed files with 67 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
doc/arm/Bv9ARM-book.xml
View File

@@ -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
why and how specific queries result in responses which
indicate an error.
Messages of this category are therefore only logged
with <command>debug</command> levels.
used to indicate why and how specific queries resulted in
responses which indicate an error. Normally, these messages
will be logged at <command>debug</command> logging levels;
note, however, that if query logging is active, some will be
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
rcode of SERVFAIL is logged as follows:
At <command>debug</command> level 1 or higher - or at
<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
detected at line 3880 of source file
<filename>query.c</filename>.
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 <filename>query.c</filename>. Log messages
of this level will particularly help identify the cause of
SERVFAIL for an authoritative server.
</para>
<para>
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 <command>debug</command> level 2 or higher, detailed
context information about recursive resolutions that resulted in
SERVFAIL will be logged. The log message will look like this:
</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,
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]
</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.
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.
</para>
<para>
The last part enclosed in square brackets shows statistics
information collected for this particular resolution
attempt.
The <varname>domain</varname> 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 <varname>domain</varname> 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.
</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
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 <command>debug</command> level 3 or higher, the same
messages as those at <command>debug</command> 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.
</para>
<para>
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 <command>debug</command> level 4 or higher, the
detailed context information logged at <command>debug</command>
level 2 will be logged for other errors than SERVFAIL and
for negative resonses such as NXDOMAIN.
</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>
starts.
If <command>querylog</command> is not specified,
then the query logging
is determined by the presence of the logging category <command>queries</command>.
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.
</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>