Commit 5b779d6b authored by Marcin Siodelski's avatar Marcin Siodelski
Browse files

[3806] Updated Logging section in the user guide.

Listed all loggers and updated the introductory text.
parent 334e6942
......@@ -85,25 +85,46 @@
</para>
<para>
If you want to specify logging for one specific library within a
daemon, you set the name to
<replaceable>daemon.library</replaceable>. For example, the logger
used by the code from libdhcpsrv used in kea-dhcp4 binary has the
full name of <quote>kea-dhcp4.dhcpsrv</quote>. If there is no entry
in Logging for a particular library, it will use the configuration
given for the whole daemon.
When diagnosing the problem with the server's operation it is often
desired to use the DEBUG logging level to obtain the verbose output
from the server and libraries it uses. However, high verbosity may
be an overkill for the logging system in cases when the server
is processing high volume traffic. To mitigate this problem, Kea
is using multiple loggers, which can be configured independently
and which are responsible for logging messages from different
functional parts of the server. If the user, trying to diagnose the
problem, has a reasonably high confidence that the problem origins
in a specific function of the server, or the problem is related
to the specific type of operation, he may enable high verbosity
only for the relevant logger, thus limiting the debug messages
to the required minimum.
</para>
<para>
To illustrate this, suppose you want the dhcpsrv library
to log messages of severity DEBUG, and the rest of the
DHCPv4 server code to log messages of severity INFO. To achieve
this you specify two loggers, one with the name
<quote>kea-dhcp4</quote> and severity INFO, and one with
the name <quote>kea-dhcp4.dhcpsrv</quote> with severity
DEBUG. As there are no entries for other libraries,
they will use the configuration for the daemon
(<quote>kea-dhcp4</quote>), so giving the desired behavior.
The loggers are associated with a particular library or binary
of Kea. However, each library or binary may (and usually does)
include multiple loggers. For example, the DHCPv4 server binary
contains separate loggers for: packet parsing, for dropped packets,
for callouts etc. Each logger "derives" its configuration from the
root logger. In the typical case, the root logger configuration
is the only logging configuration specified in the configuration
file. Creating a specific configuration for the selected logger,
thus overriding the configuration settings specified in the
root logger configuration, requires putting its configuration
aside of the root logger's configuration with some of the
parameters modified.
</para>
<para>
To illustrate this, suppose you are using the DHCPv4 server
with the root logger <quote>kea-dhcp4</quote> logging at the
INFO level. In order to enable DEBUG verbosity for the DHCPv4
packet drops, you must create configuration entry for the
logger called <quote>kea-dhcp4.bad_packet</quote> and specify
severity DEBUG for this logger. All other configuration
parameters may be omited for this logger if the logger should
use the default values specified in the root logger's
configuration.
</para>
<!-- we don't support asterisk anymore.
......@@ -128,21 +149,6 @@
(<quote>kea-dhcp4</quote>).
</para>
<para>
One final note about the naming. When specifying the daemon name
within a logger, use the name of the binary file,
e.g. <quote>kea-dhcp4</quote> for the DHCPv4 server,
<quote>kea-dhcp6</quote> for the DHCPv6 server, etc. When the
message is logged, the message will include the name of the process
(e.g. <quote>kea-dhcp4</quote>) followed by the specific component
in that process, e.g. <quote>hooks</quote>. It is possible to
specify either just the process name (<quote>kea-dhcp4</quote>, will
apply to everything logged within that process) or process name
followed by specific logger,
e.g. <quote>kea-dhcp4.hooks</quote>. That will apply only to
messages originating from that component.
</para>
<para>
Currently defined loggers are:
</para>
......@@ -158,7 +164,7 @@
<simpara><command>kea-dhcp4.bad_packet</command> - this is the
logger used by the DHCPv4 server deamon for logging inbound client
packets that were dropped or to which the server responded with a
NAK. The allows adminstrators to configure a separate log
DHCPNAK. The allows adminstrators to configure a separate log
output that contains only packet drop and reject entries.</simpara>
</listitem>
<listitem>
......@@ -174,8 +180,18 @@
</listitem>
<listitem>
<simpara><command>kea-dhcp4.hooks</command> - this logger is used
during DHCPv4 hooks operation, i.e. anything related to user
libraries will be logged using this logger.</simpara>
by the hooks framework to log messages related to the execution of
callouts for various hook points. This logger doesn't log messages
which pertain to actions on the server side being the result of
the callout execution, e.g. skipping packet parsing by the server
because the callout has indicated that it has parsed the packet
already.</simpara>
</listitem>
<listitem>
<simpara><command>kea-dhcp4.hostname</command> - this logger is
used by the DHCPv4 server to log messages related to the Client
FQDN and Hostname option processing. It also includes log messages
related to the relevant DNS updates.</simpara>
</listitem>
<listitem>
<simpara><command>kea-dhcp4.hosts</command> - this logger is used
......@@ -183,6 +199,42 @@
of the DHCPv4 host reservations, i.e. retrieval of the resevations
and adding new reservations.</simpara>
</listitem>
<listitem>
<simpara><command>kea-dhcp4.lease</command> - this logger is used
by the DHCPv4 server to log messages related to the lease allocation.
These messages are logged for each processed packet. The messages
include detailed information about the allocated or offered leases,
errors during the lease allocation etc.
</simpara>
</listitem>
<listitem>
<simpara><command>kea-dhcp4.options</command> - this logger is
used by the DHCPv4 server to log messages related to processing
of the options in the DHCPv4 messages, i.e. parsing options,
encoding options into on-wire format and packet classification
using options contained in the received packets.</simpara>
</listitem>
<listitem>
<simpara><command>kea-dhcp4.packet</command> - this logger
is mostly used to log messages related to transmission of the DHCPv4
packets, i.e. packet reception and sending a response. Such messages
include the information about the source and destination IP addresses
and interfaces used to transmit packets. This logger is also used
to log messages related to subnet selection, as this selection is
usually based on the IP addresses and/or interface names, which can
be retrieved from the received packet, even before the DHCPv4 message
carried in the packet is parsed.
</simpara>
</listitem>
<listitem>
<simpara><command>kea-dhcp4.server-hook</command> - this logger is
used by the DHCPv4 server to log messages pertaining to the
preparations for the callouts execution by the server and to the
actions taken by the server as a result of the callouts execution.
Note that it is a different logger than the
<command>kea-dhcp4.hooks</command> logger.
</simpara>
</listitem>
<listitem>
<simpara><command>kea-dhcp6</command> - this is the root logger for
the DHCPv6 server. All components used by the DHCPv6 server inherit
......@@ -202,8 +254,12 @@
</listitem>
<listitem>
<simpara><command>kea-dhcp6.hooks</command> - this logger is used
during DHCPv6 hooks operation, i.e. anything related to user
libraries will be logged using this logger.</simpara>
by the hooks framework to log messages related to the execution of
callouts for various hook points. This logger doesn't log messages
which pertain to actions on the server side being the result of
the callout execution, e.g. skipping packet parsing by the server
because the callout has indicated that it has parsed the packet
already.</simpara>
</listitem>
<listitem>
<simpara><command>kea-dhcp6.hosts</command> - this logger is used
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment