mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-31 14:05:33 +00:00
trac1011: more logging doc formatting
This commit is contained in:
reed
@@ -1588,53 +1588,98 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
The three most important elements of a logger configuration are the name (the component that is generating the messages), the severity (what to log), and the output_options (where to log).
|
||||
The three most important elements of a logger configuration
|
||||
are the name (the component that is generating the
|
||||
messages), the severity (what to log), and the output_options
|
||||
(where to log).
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
name (string)
|
||||
|
||||
Each logger in the system has a name, the name being that of the component using it to log messages. For instance, if you want to configure logging for the resolver module, you add an entry for a logger named 'Resolver'. This configuration will then be used by the loggers in the Resolver module, and all the libraries used by it.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
Each logger in the system has a name, the name being that
|
||||
of the component using it to log messages. For instance,
|
||||
if you want to configure logging for the resolver module,
|
||||
you add an entry for a logger named 'Resolver'. This
|
||||
configuration will then be used by the loggers in the
|
||||
Resolver module, and all the libraries used by it.
|
||||
|
||||
<!-- TODO: how to know these names? -->
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
If you want to specify logging for one specific library
|
||||
within the module, you set the name to 'module.library'.
|
||||
For example, the logger used by the nameserver address
|
||||
store component has the full name of 'Resolver.nsas'. If
|
||||
there is no entry in Logging for a particular library,
|
||||
it will use the configuration given for the module.
|
||||
|
||||
If you want to specify logging for one specific library within the module, you set the name to 'module.library'. For example, the logger used by the nameserver address store component has the full name of 'Resolver.nsas'. If there is no entry in Logging for a particular library, it will use the configuration given for the module.
|
||||
<!-- TODO: how to know these specific names? -->
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
To illustrate this, suppose you want the cache library to log messages of severity DEBUG, and the rest of the resolver code to log messages of severity INFO. To achieve this you specify two loggers, one with the name 'Resolver' and severity INFO, and one with the name 'Resolver.cache' with severity DEBUG. As there are no entries for other libraries (e.g. the nsas), they will use the configuration for the module ('Resolver'), so giving the desired behavior.
|
||||
|
||||
To illustrate this, suppose you want the cache library
|
||||
to log messages of severity DEBUG, and the rest of the
|
||||
resolver code to log messages of severity INFO. To achieve
|
||||
this you specify two loggers, one with the name 'Resolver'
|
||||
and severity INFO, and one with the name 'Resolver.cache'
|
||||
with severity DEBUG. As there are no entries for other
|
||||
libraries (e.g. the nsas), they will use the configuration
|
||||
for the module ('Resolver'), so giving the desired
|
||||
behavior.
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
One special case is that of a module name of '*', which is interpreted as 'any module'. 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. '*.config" specifies the configuration library code in whatever module is using it).
|
||||
One special case is that of a module name of '*', which
|
||||
is interpreted as 'any module'. 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. '*.config" specifies the configuration
|
||||
library code in whatever module is using it).
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
If there are multiple logger specifications in the configuration that might match a particular logger, the specification with the more specific logger name takes precedence. For example, if there are entries for for both '*' and 'Resolver', the resolver module - and all libraries it uses - will log messages according to the configuration in the second entry ('Resolver'). All other modules will use the configuration of the first entry ('*'). If there was also a configuration entry for 'Resolver.cache', the cache library within the resolver would use that in preference to the entry for 'Resolver'.
|
||||
If there are multiple logger specifications in the
|
||||
configuration that might match a particular logger, the
|
||||
specification with the more specific logger name takes
|
||||
precedence. For example, if there are entries for for
|
||||
both '*' and 'Resolver', the resolver module - and all
|
||||
libraries it uses - will log messages according to the
|
||||
configuration in the second entry ('Resolver'). All other
|
||||
modules will use the configuration of the first entry
|
||||
('*'). If there was also a configuration entry for
|
||||
'Resolver.cache', the cache library within the resolver
|
||||
would use that in preference to the entry for 'Resolver'.
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
One final note about the naming. When specifying the module name within a logger, use the name of the module as specified in bindctl, e.g. 'Resolver' for the resolver module, 'Xfrout' for the xfrout module etc. When the message is logged, the message will include the name of the logger generating the message, but with the module name replaced by the name of the process implementing the module (so for example, a message generated by the 'Auth.cache' logger will appear in the output with a logger name of 'b10-auth.cache').
|
||||
|
||||
One final note about the naming. When specifying the
|
||||
module name within a logger, use the name of the module
|
||||
as specified in bindctl, e.g. 'Resolver' for the resolver
|
||||
module, 'Xfrout' for the xfrout module etc. When the
|
||||
message is logged, the message will include the name of
|
||||
the logger generating the message, but with the module
|
||||
name replaced by the name of the process implementing
|
||||
the module (so for example, a message generated by the
|
||||
'Auth.cache' logger will appear in the output with a
|
||||
logger name of 'b10-auth.cache').
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1642,19 +1687,19 @@ One final note about the naming. When specifying the module name within a logger
|
||||
|
||||
severity (string)
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
This specifies the category of messages logged.
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
This specifies the category of messages logged.
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
Each message is logged with an associated severity which may be one of the following (in descending order of severity):
|
||||
Each message is logged with an associated severity which
|
||||
may be one of the following (in descending order of
|
||||
severity):
|
||||
|
||||
FATAL
|
||||
ERROR
|
||||
@@ -1662,13 +1707,17 @@ Each message is logged with an associated severity which may be one of the follo
|
||||
INFO
|
||||
DEBUG
|
||||
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
When the severity of a logger is set to one of these values, it will only log messages of that severity, and the severities below it. The severity may also be set to NONE, in which case all messages from that logger are inhibited.
|
||||
When the severity of a logger is set to one of these
|
||||
values, it will only log messages of that severity, and
|
||||
the severities below it. The severity may also be set to
|
||||
NONE, in which case all messages from that logger are
|
||||
inhibited.
|
||||
|
||||
<!-- TODO: worded wrong? If I set to INFO, why would it show DEBUG which is literally below in that list? -->
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1680,16 +1729,15 @@ output_options (list)
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
Each logger can have zero or more output_options. These specify where log messages are sent to. These are explained in detail below.
|
||||
|
||||
Each logger can have zero or more output_options. These
|
||||
specify where log messages are sent to. These are explained
|
||||
in detail below.
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
The other options for a logger are:
|
||||
|
||||
The other options for a logger are:
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1701,23 +1749,20 @@ debuglevel (integer)
|
||||
|
||||
<para>
|
||||
|
||||
When a logger's severity is set to DEBUG, this value
|
||||
specifies what debug messages should be printed. It ranges
|
||||
from 0 (least verbose) to 99 (most verbose). The general
|
||||
classification of debug message types is
|
||||
|
||||
When a logger's severity is set to DEBUG, this value specifies what debug messages should be printed. It ranges from 0 (least verbose) to 99 (most verbose). The general classification of debug message types is
|
||||
|
||||
<!-- TODO: complete this sentence -->
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
TODO; there's a ticket to determine these levels, see #1074
|
||||
|
||||
|
||||
</para>
|
||||
<!-- TODO; there's a ticket to determine these levels, see #1074 -->
|
||||
|
||||
<para>
|
||||
|
||||
If severity for the logger is not DEBUG, this value is ignored.
|
||||
|
||||
If severity for the logger is not DEBUG, this value is ignored.
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1725,19 +1770,19 @@ If severity for the logger is not DEBUG, this value is ignored.
|
||||
|
||||
additive (true or false)
|
||||
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
If this is true, the output_options from the parent will be used. For example, if there are two loggers configured; 'Resolver' and 'Resolver.cache', and additive is true in the second, it will write the log messages not only to the destinations specified for 'Resolver.cache', but also to the destinations as specified in the output_options in the logger named Resolver'.
|
||||
If this is true, the output_options from the parent will
|
||||
be used. For example, if there are two loggers configured;
|
||||
'Resolver' and 'Resolver.cache', and additive is true in
|
||||
the second, it will write the log messages not only to
|
||||
the destinations specified for 'Resolver.cache', but also
|
||||
to the destinations as specified in the output_options
|
||||
in the logger named Resolver'.
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
TODO: check this
|
||||
<!-- TODO: check this -->
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1748,8 +1793,9 @@ TODO: check this
|
||||
|
||||
<para>
|
||||
|
||||
The main settings for an output option are the 'destination' and a value called 'output', the meaning of which depends on the destination that is set.
|
||||
|
||||
The main settings for an output option are the 'destination'
|
||||
and a value called 'output', the meaning of which depends
|
||||
on the destination that is set.
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1757,13 +1803,11 @@ The main settings for an output option are the 'destination' and a value called
|
||||
|
||||
destination (string)
|
||||
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
The destination is the type of output. It can be one of:
|
||||
|
||||
The destination is the type of output. It can be one of:
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1777,30 +1821,29 @@ The destination is the type of output. It can be one of:
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
output (string)
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
Depending on what is set as the output destination, this value is interpreted as follows:
|
||||
Depending on what is set as the output destination, this
|
||||
value is interpreted as follows:
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
* destination is 'console'
|
||||
'output' must be one of 'stdout' (messages printed to standard output) or 'stderr' (messages printed to standard error).
|
||||
|
||||
'output' must be one of 'stdout' (messages printed to standard output) or 'stderr' (messages printed to standard error).
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
* destination is 'file'
|
||||
|
||||
The value of output is interpreted as a file name; log messages will be appended to this file.
|
||||
|
||||
|
||||
@@ -1809,15 +1852,14 @@ Depending on what is set as the output destination, this value is interpreted as
|
||||
<para>
|
||||
|
||||
* destination is 'syslog'
|
||||
|
||||
The value of output is interpreted as the syslog facility (e.g. 'local0') that should be used for log messages.
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
The other options for output_options are:
|
||||
|
||||
The other options for output_options are:
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1825,13 +1867,14 @@ The other options for output_options are:
|
||||
|
||||
flush (true of false)
|
||||
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
Flush buffers after each log message. Doing this will reduce performance but will ensure that if the program terminates abnormally, all messages up to the point of termination are output.
|
||||
|
||||
Flush buffers after each log message. Doing this will
|
||||
reduce performance but will ensure that if the program
|
||||
terminates abnormally, all messages up to the point of
|
||||
termination are output.
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1839,20 +1882,21 @@ Flush buffers after each log message. Doing this will reduce performance but wil
|
||||
|
||||
maxsize (integer)
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
Only relevant when destination is file, this is maximum
|
||||
file size of output files in bytes. When the maximum size
|
||||
is reached, the file is renamed (a ".1" is appended to
|
||||
the name - if a ".1" file exists, it is renamed ".2"
|
||||
etc.) and a new file opened.
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
Only relevant when destination is file, this is maximum file size of output files in bytes. When the maximum size is reached, the file is renamed (a ".1" is appended to the name - if a ".1" file exists, it is renamed ".2" etc.) and a new file opened.
|
||||
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
If this is 0, no maximum file size is used.
|
||||
|
||||
If this is 0, no maximum file size is used.
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1860,12 +1904,13 @@ If this is 0, no maximum file size is used.
|
||||
|
||||
maxver (integer)
|
||||
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
Maximum number of old log files to keep around when rolling the output file. Only relevant when destination if 'file'.
|
||||
Maximum number of old log files to keep around when
|
||||
rolling the output file. Only relevant when destination
|
||||
if 'file'.
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1876,8 +1921,10 @@ Maximum number of old log files to keep around when rolling the output file. Onl
|
||||
|
||||
<para>
|
||||
|
||||
In this example we want to set the global logging to write to the file /var/log/my_bind10.log, at severity WARN. We want the authoritative server to log at DEBUG with debuglevel 40, to a different file (/tmp/debug_messages).
|
||||
|
||||
In this example we want to set the global logging to
|
||||
write to the file /var/log/my_bind10.log, at severity
|
||||
WARN. We want the authoritative server to log at DEBUG
|
||||
with debuglevel 40, to a different file (/tmp/debug_messages).
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1885,7 +1932,6 @@ In this example we want to set the global logging to write to the file /var/log/
|
||||
|
||||
Start bindctl
|
||||
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@@ -1895,20 +1941,19 @@ Start bindctl
|
||||
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>
|
||||
|
||||
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;
|
||||
|
||||
Let's first add a default logger;
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1924,8 +1969,8 @@ Logging/loggers/ list (modified)
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
The loggers value line changed to indicate that it is no longer an empty list;
|
||||
The loggers value line changed to indicate that it is no
|
||||
longer an empty list;
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1943,9 +1988,9 @@ Logging/loggers[0]/output_options [] list (default)
|
||||
|
||||
<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.
|
||||
|
||||
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>
|
||||
|
||||
@@ -1965,9 +2010,8 @@ Logging/loggers[0]/output_options [] list (default)
|
||||
|
||||
<para>
|
||||
|
||||
|
||||
Of course, we need to specify where we want the log messages to go, so we add an entry for an output option.
|
||||
|
||||
Of course, we need to specify where we want the log
|
||||
messages to go, so we add an entry for an output option.
|
||||
|
||||
</para>
|
||||
|
||||
@@ -1987,8 +2031,7 @@ Logging/loggers[0]/output_options[0]/maxver 0 integer (default)
|
||||
|
||||
<para>
|
||||
|
||||
These aren't the values we are looking for.
|
||||
|
||||
These aren't the values we are looking for.
|
||||
|
||||
</para>
|
||||
|
||||
@@ -2004,7 +2047,8 @@ These aren't the values we are looking for.
|
||||
|
||||
<para>
|
||||
|
||||
Which would make the entire configuration for this logger look like:
|
||||
Which would make the entire configuration for this logger
|
||||
look like:
|
||||
|
||||
</para>
|
||||
|
||||
@@ -2026,8 +2070,8 @@ Logging/loggers[0]/output_options[0]/maxver 8 integer (modified)
|
||||
|
||||
<para>
|
||||
|
||||
That looks OK, so let's commit it before we add the configuration for the authoritative server's logger.
|
||||
|
||||
That looks OK, so let's commit it before we add the
|
||||
configuration for the authoritative server's logger.
|
||||
|
||||
</para>
|
||||
|
||||
@@ -2035,13 +2079,12 @@ That looks OK, so let's commit it before we add the configuration for the author
|
||||
|
||||
<screen>> <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.
|
||||
|
||||
Now that we have set it, and checked each value along
|
||||
the way, adding a second entry is quite similar.
|
||||
|
||||
</para>
|
||||
|
||||
@@ -2061,9 +2104,10 @@ Now that we have set it, and checked each value along the way, adding a second e
|
||||
|
||||
<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 authoritative server use the same settings as the rest.
|
||||
|
||||
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 authoritative server use the
|
||||
same settings as the rest.
|
||||
|
||||
</para>
|
||||
|
||||
@@ -2077,7 +2121,8 @@ And that's it. Once we have found whatever it was we needed the debug messages f
|
||||
|
||||
<para>
|
||||
|
||||
And every module will now be using the values from the logger named '*'.
|
||||
And every module will now be using the values from the
|
||||
logger named '*'.
|
||||
|
||||
</para>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user