|
|
@@ -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 — 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
|
|
|
@@ -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>
|
|
|
|
Tomek Mrugalski