Commit 28811b7f authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰

[3536] Logging section in User's Guide updated.

parent 85ec71f6
......@@ -11,92 +11,84 @@
<title>Logging configuration</title>
<para>
During its operation Kea may produce many messages. They differ in
severity (some are more important than others) and source (some are
produced by specific components, e.g. hooks). It is useful to understand
which log messages are needed and which are not. For example debug level
messages can be safely ignored in a typical deployment. They are,
however, very useful when debugging a problem.
</para>
<para>
The logging system in Kea is configured through the
Logging module. All modules will look at the
configuration in Logging to see what should be logged and
to where.
<!-- TODO: what is context of Logging module for readers of this guide? -->
<replaceable>Logging</replaceable> module. All modules will look at the
configuration in <replaceable>Logging</replaceable> to see what should
be logged and to where. This allows sharing identical logging
configuration between components.
</para>
<section>
<title>Loggers</title>
<para>
Within Kea, a message is logged through a component
called a "logger". Different parts of log messages
through different loggers, and each logger can be configured
independently of one another.
</para>
<para>
In the Logging module, you can specify the configuration
for zero or more loggers; any that are not specified will
take appropriate default values.
</para>
<para>
The three most important elements of a logger configuration
are the <option>name</option> (the component that is
generating the messages), the <option>severity</option>
(what to log), and the <option>output_options</option>
(where to log).
</para>
<section>
<title>name (string)</title>
<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 Dhcp4 module,
you add an entry for a logger named <quote>Dhcp4</quote>. This
configuration will then be used by the loggers in the
Dhcp4 module, and all the libraries used by it (unless
a library defines its own logger).
Each logger in the system has a name, the name being that of the
component binary file using it to log messages. For instance, if you
want to configure logging for the Dhcp4 module, you add an entry for
a logger named <quote>kea-dhcp4</quote>. This configuration will
then be used by the loggers in the Dhcp4 module, and all the
libraries used by it (unless a library defines its own logger).
</para>
<!-- TODO: later we will have a way to know names of all modules
<!-- TODO: later we will have a way to know names of all modules -->
Right now you can only see what their names are if they are running
(a simple 'help' without anything else in bindctl for instance).
-->
<para>
If you want to specify logging for one specific library within the
module, you set the name to
<replaceable>module.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 module.
</para>
If you want to specify logging for one specific library
within the module, you set the name to
<replaceable>module.library</replaceable>. For example, the
logger used by the nameserver address store component
has the full name of <quote>Dhcp4.dhcpsrv</quote>. If
there is no entry in Logging for a particular library,
it will use the configuration given for the module.
</para>
<para>
To illustrate this, suppose you want the dhcpsrv library
to log messages of severity DEBUG, and the rest of the
Dhcp4 code to log messages of severity INFO. To achieve
this you specify two loggers, one with the name
<quote>Dhcp4</quote> and severity INFO, and one with
the name <quote>Dhcp4.dhcpsrv</quote> with severity
DEBUG. As there are no entries for other libraries,
they will use the configuration for the module
(<quote>Dhcp4</quote>), so giving the desired behavior.
</para>
<para>
To illustrate this, suppose you want the dhcpsrv library
to log messages of severity DEBUG, and the rest of the
Dhcp4 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 module
(<quote>kea-dhcp4</quote>), so giving the desired behavior.
</para>
<!--
<para>
One special case is that of a module name of <quote>*</quote>
(asterisks), which is interpreted as <emphasis>any</emphasis>
module. You can set global logging options by using this,
......@@ -104,68 +96,72 @@ Right now you can only see what their names are if they are running
that is used by multiple modules (e.g. <quote>*.config</quote>
specifies the configuration library code in whatever
module is using it).
</para> -->
</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
both <quote>*</quote> and <quote>Dhcp4</quote>, the
Dhcp4 module &mdash; and all libraries it uses &mdash;
will log messages according to the configuration in the
second entry (<quote>Dhcp4</quote>). All other modules
will use the configuration of the first entry
(<quote>*</quote>).
</para>
<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 both <quote>kea-dhcp4</quote> and
<quote>kea-dhcp4.dhcpsrv</quote>, the Dhcp4 module &mdash; and all
libraries it uses that are not dhcpsrv &mdash; will log messages
according to the configuration in the first entry
(<quote>kea-dhcp4</quote>).
</para>
One final note about the naming. When specifying the
module name within a logger, use the name of the binary file,
e.g. <quote>kea-dhcp4</quote> for the DHCPv4 module,
<quote>kea-dhcp6</quote> for the DHCPv6 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
<quote>DHCPv4</quote> logger will appear in the output
with a logger name of <quote>kea-dhcp4</quote>).
<para>
One final note about the naming. When specifying the module name
within a logger, use the name of the binary file,
e.g. <quote>kea-dhcp4</quote> for the DHCPv4 module,
<quote>kea-dhcp6</quote> for the DHCPv6 module, 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>
<para>
Currently defined loggers are:
</para>
<para>
Currently defined loggers are:
</para>
<itemizedlist>
<listitem>
<simpara>kea-dhcp4.dhcp4</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp6.dhcp6</simpara>
<simpara>kea-dhcp4.dhcpsrv</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp-ddns.dhcpddns</simpara>
<simpara>kea-dhcp4.hooks</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp4.dhcpsrv</simpara>
<simpara>kea-dhcp6.dhcp6</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp6.dhcpsrv</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp6.hooks</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp-ddns.dhcpddns</simpara>
</listitem>
</itemizedlist>
<para>Additional loggers may be defined in the future.</para>
<para>Additional loggers may be defined in the future. The easiest
way to find out the logger name is to configure all logging to go
to a single destination and look for specific logger names. See
<xref linkend="logging-message-format"/> for details.</para>
</section>
<section>
<title>severity (string)</title>
<para>
This specifies the category of messages logged.
Each message is logged with an associated severity which
may be one of the following (in descending order of
......@@ -448,7 +444,7 @@ file be created.</para>
</section>
<section>
<section id="logging-message-format">
<title>Logging Message Format</title>
<para>
......@@ -499,7 +495,8 @@ file be created.</para>
case, <command>kea-dhcp4</command>) and the module
within the program from which the message originated
(which is the name of the common library used by DHCP server
implementations).
implementations). The number after the slash is a process id
(pid).
</para></listitem>
</varlistentry>
......
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