Commit 4fdd7238 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰

[3536] Changes after review:

 - Logging section updated.
 - Missing coma in kea.conf.pre added
 - ${localstatedir}/log is now created
parent 065949da
......@@ -119,6 +119,10 @@ cppcheck:
--template '{file}:{line}: check_fail: {message} ({severity},{id})' \
src
# These steps are necessary during installation
install-exec-hook:
mkdir -p $(DESTDIR)${localstatedir}/log/
### include tool to generate documentation from log message specifications
### in the distributed tarball:
EXTRA_DIST = tools/system_messages.py
......
......@@ -4,6 +4,18 @@
<!ENTITY mdash "&#x2014;" >
]>
<!-- Note: Please use the following terminology:
- daemon - one process (e.g. kea-dhcp4)
- component - one piece of code within a daemon (e.g. libdhcp or hooks)
- server - currently equal to daemon, but the difference will be more
prominent once we add client or relay support
- logger - one instance of isc::log::Logger
- structure - an element in config file (e.g. "Dhcp4")
Do not use:
- module => daemon
-->
<chapter id="logging">
<title>Logging</title>
......@@ -14,33 +26,41 @@
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.
which log messages are needed and which are not and configure your
logging appropriately. 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
<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.
<replaceable>Logging</replaceable> structure in your configuration
file. All daemons (e.g. a DHCPv4 and DHCPv6 servers) will look at the
configuration in the <replaceable>Logging</replaceable> structure to see
what should be logged and to where. This allows sharing identical
logging configuration between daemons.
</para>
<section>
<title>Loggers</title>
<para>
Within Kea, a message is logged through a component
called a "logger". Different parts of log messages
Within Kea, a message is logged through an entity
called a "logger". Different parts of the code log messages
through different loggers, and each logger can be configured
independently of one another.
independently of one another. For example there are different
components that deal with hooks ("hooks" logger) and with
DHCP engine ("dhcpsrv" logger).
</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.
In the Logging structure in a configuration file you can
specify the configuration for zero or more loggers. If there are
no specified loggers, the code will use default values which
cause Kea to log messages on at least INFO severity to standard
output.
<!-- @todo: add reference to section about controlling default
behavior with env. variables, after #3591 is merged. -->
</para>
<para>
......@@ -57,45 +77,44 @@
<para>
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).
want to configure logging for the DHCPv4 server, you add an entry
for a logger named <quote>kea-dhcp4</quote>. This configuration will
then be used by the loggers in the DHCPv4 server, and all the
libraries used by it (unless a library defines its own logger and
there is specific logger configuration that applies to that logger).
</para>
<!-- TODO: later we will have a way to know names of all modules -->
<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
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 module.
given for the whole daemon.
</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
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 module
they will use the configuration for the daemon
(<quote>kea-dhcp4</quote>), so giving the desired behavior.
</para>
<!--
<!-- we don't support asterisk anymore.
<para>
One special case is that of a module name of <quote>*</quote>
One special case is that of a component name of <quote>*</quote>
(asterisks), which is interpreted as <emphasis>any</emphasis>
module. You can set global logging options by using this,
component. 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. <quote>*.config</quote>
that is used by multiple daemons (e.g. <quote>*.config</quote>
specifies the configuration library code in whatever
module is using it).
daemon is using it).
</para> -->
<para>
......@@ -103,17 +122,17 @@
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
<quote>kea-dhcp4.dhcpsrv</quote>, the DHCPv4 server &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>
<para>
One final note about the naming. When specifying the module name
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 module,
<quote>kea-dhcp6</quote> for the DHCPv6 module, etc. When the
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
......@@ -130,25 +149,41 @@
<itemizedlist>
<listitem>
<simpara>kea-dhcp4.dhcp4</simpara>
<simpara><command>kea-dhcp4.dhcp4</command> - this is the logger
used by DHCPv4 server code in cases, where there is no more
specialized logger.</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp4.dhcpsrv</simpara>
<simpara><command>kea-dhcp4.dhcpsrv</command> - this logger is used
by the libdhcpsrv library. This covers mostly DHCP engine (the lease
allocation and renewal process), database operations and
configuration.</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp4.hooks</simpara>
<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>
</listitem>
<listitem>
<simpara>kea-dhcp6.dhcp6</simpara>
<simpara><command>kea-dhcp6.dhcp6</command> - this logger is used
by DHCPv6 server code in cases, where there is no more specialzed
logger.</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp6.dhcpsrv</simpara>
<simpara><command>kea-dhcp6.dhcpsrv</command> - this logger is used
by the libdhcpsrv library. This covers mostly DHCP engine (the lease
allocation and renewal process), database operations and
configuration.</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp6.hooks</simpara>
<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>
</listitem>
<listitem>
<simpara>kea-dhcp-ddns.dhcpddns</simpara>
<simpara><command>kea-dhcp-ddns.dhcpddns</command> - this is the
default logger for kea-dhcp-ddns daemon. This logger is not used
in DHCPv4 or DHCPv6 servers.</simpara>
</listitem>
</itemizedlist>
......@@ -249,26 +284,6 @@ TODO; there's a ticket to determine these levels, see #1074
</para>
</section>
<section>
<title>additive (true or false)</title>
<para>
If this is true, the <option>output_options</option> from
the parent will be used. For example, if there are two
loggers configured; <quote>Dhcp4</quote> and
<quote>Dhcp4.dhcpsrv</quote>, and <option>additive</option>
is true in the second, it will write the log messages
not only to the destinations specified for
<quote>Dhcp4.dhcpsrv</quote>, but also to the destinations
as specified in the <option>output_options</option> in
the logger named <quote>Dhcp4</quote>.
</para>
</section>
</section>
<section>
......@@ -490,9 +505,9 @@ file be created.</para>
<varlistentry>
<term>[kea-dhcp4.dhcpsrv/27456]</term>
<listitem><para>
The source of the message. This comprises two components:
The source of the message. This comprises two elements:
the Kea process generating the message (in this
case, <command>kea-dhcp4</command>) and the module
case, <command>kea-dhcp4</command>) and the component
within the program from which the message originated
(which is the name of the common library used by DHCP server
implementations). The number after the slash is a process id
......
......@@ -92,7 +92,7 @@
],
"severity": "INFO",
"debuglevel": 0
}
},
{
"name": "kea-dhcp-ddns",
"output_options": [
......
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