<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,
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 — and all libraries it uses —
- 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 — and all
+ libraries it uses that are not dhcpsrv — 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
</section>
- <section>
+ <section id="logging-message-format">
<title>Logging Message Format</title>
<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>
projects / thirdparty / kea.git / commitdiff
