</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.
(<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>
<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>
</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
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
</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
projects / thirdparty / kea.git / commitdiff
