Skip to content

GitLab

Commit 2cf3f6b9 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

Merge branch 'trac3536'

parents 7ca55f1b b67d4b7a
Hide whitespace changes
Inline Side-by-side
Makefile.am
View file @ 2cf3f6b9
......@@ -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
......
doc/guide/logging.xml
View file @ 2cf3f6b9
......@@ -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>
......@@ -11,161 +23,198 @@
<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 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
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> structure in your configuration
file. All daemons (e.g. DHCPv4 and DHCPv6 servers) will use the
configuration in the <replaceable>Logging</replaceable> structure to see
what should be logged and to where. This allows for 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 loggers specified, 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>
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 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
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 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.
</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
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.
</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>
<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 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>
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 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>
<para>
Currently defined loggers are:
</para>
<para>
Currently defined loggers are:
</para>
<itemizedlist>
<listitem>
<simpara>kea-dhcp4.dhcp4</simpara>
<simpara><command>kea-dhcp4</command> - this is the root logger for
the DHCPv4 server. All components used by the DHCPv4 server inherit
the settings from this logger if there is no specialized logger
provided.</simpara>
</listitem>
<listitem>
<simpara><command>kea-dhcp4.dhcp4</command> - this is the logger
used solely by the DHCPv4 server deamon. This logger does not
specify logging settings for libraries used by the deamon.</simpara>
</listitem>
<listitem>
<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><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</command> - this is the root logger for
the DHCPv6 server. All components used by the DHCPv6 server inherit
the settings from this logger if there is no specialized logger
provided.</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp-ddns.dhcpddns</simpara>
<simpara><command>kea-dhcp6.dhcp6</command> - this is the logger
used solely by the DHCPv6 server deamon. This logger does not
specify logging settings for libraries used by the daemon.</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp4.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.dhcpsrv</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><command>kea-dhcp-ddns</command> - this is the root logger for
the kea-dhcp-ddns deamon. All components used by this deamon inherit
the settings from this logger if there is no specialized logger
provided.</simpara>
</listitem>
<listitem>
<simpara><command>kea-dhcp-ddns.dhcpddns</command> - this is the logger
used solely by the kea-dhcp-ddns deamon. This logger does not
specify logging settings for libraries used by the deamon.</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
......@@ -253,26 +302,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>
......@@ -448,7 +477,7 @@ file be created.</para>
</section>
<section>
<section id="logging-message-format">
<title>Logging Message Format</title>
<para>
......@@ -494,12 +523,13 @@ 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).
implementations). The number after the slash is a process id
(pid).
</para></listitem>
</varlistentry>
......
src/bin/keactrl/kea.conf.pre
View file @ 2cf3f6b9
......@@ -77,10 +77,30 @@
{
"loggers": [
{
"name": "kea",
"name": "kea-dhcp4",
"output_options": [
{
"output": "@localstatedir@/log/kea.log"
"output": "@localstatedir@/log/kea-dhcp4.log"
}
],
"severity": "INFO",
"debuglevel": 0
},
{
"name": "kea-dhcp6",
"output_options": [
{
"output": "@localstatedir@/log/kea-dhcp6.log"
}
],
"severity": "INFO",
"debuglevel": 0
},
{
"name": "kea-dhcp-ddns",
"output_options": [
{
"output": "@localstatedir@/log/kea-ddns.log"
}
],
"severity": "INFO",
......
src/bin/keactrl/keactrl.conf.in
View file @ 2cf3f6b9
......@@ -21,7 +21,7 @@ dhcp4=yes
dhcp6=yes
# Start DHCP DDNS server?
dhcp_ddns=yes
dhcp_ddns=no
# Be verbose?
kea_verbose=no
Supports Markdown
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