logging.xml 35.6 KB
Newer Older
1 2 3 4 5 6 7 8
<!--
 - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
 -
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
-->

9 10
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="logging">
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
  <title>Logging</title>

  <section>
    <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 section in your configuration
      file. All daemons (e.g. DHCPv4 and DHCPv6 servers) will use the
      configuration in the Logging section to see
      what should be logged and to where. This allows for sharing identical
      logging configuration between daemons.
    </para>
33 34

    <section>
35 36 37 38 39 40 41 42 43 44 45 46 47 48
      <title>Loggers</title>
      <para>
        Within Kea, a message is logged through an entity called a
        "logger". Different components log messages through different
        loggers, and each logger can be configured independently of
        one another. Some components, in particular the DHCP server
        processes, may use multiple loggers to log messages pertaining
        to different logical functions of the component. For example,
        the DHCPv4 server uses one logger for messages
        pertaining to packet reception and transmission, another
        logger for messages related to lease allocation and so on.
        Some of the libraries used by the Kea servers, e.g. libdhcpsrv,
        use their own loggers.
      </para>
49 50

      <para>
51 52 53 54
        Users implementing hooks libraries (code attached to the server at
        runtime) are responsible for creating the loggers used by those
        libraries. Such loggers should have unique names, different
        from the logger names used by Kea. In this way the
Francis Dupont's avatar
Francis Dupont committed
55
        messages output by the hooks library can be distinguished from
56 57 58 59 60
        messages issued by the core Kea code. Unique names also allow
        the loggers to be configured independently of loggers used
        by Kea.  Whenever it makes sense, a hook library can use multiple
        loggers to log messages pertaining to different logical parts
        of the library.
61
      </para>
62

63
      <para>
64 65 66 67
        In the Logging section of a configuration file you can specify the
        configuration for zero or more loggers (including loggers used by the
        proprietary hooks libraries). If there are no loggers specified, the
        code will use default values: these cause Kea to log messages of INFO
68 69 70
        severity or greater to standard output. There is also a small
        time window after Kea has been started, but has not yet read its
        configuration. Logging in this short period can be controlled
71
        using environment variables. For details, see <xref linkend="logging-during-startup"/>.
72 73
      </para>

74 75 76 77 78 79 80 81
      <para>
        The three main elements of a logger configuration are:
        <command>name</command> (the component that is generating the messages),
        the <command>severity</command> (what to log), and the
        <command>output_commands</command> (where to log).  There is also a
        <command>debuglevel</command> element, which is only relevant if
        debug-level logging has been selected.
      </para>
82

83 84
      <section>
        <title>name (string)</title>
85
        <para>
86 87 88 89 90 91 92
          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).
93 94 95
        </para>

        <para>
96 97 98 99 100 101 102 103 104 105 106 107
          When tracking down an issue with the server's operation, use of
          DEBUG logging is required to obtain the verbose output needed for
          problems diagnosis.  However, the high verbosity is likely to
          overwhelm the logging system in cases when the server
          is processing high volume traffic. To mitigate this problem, use
          can be made of the fact that Kea uses multiple loggers for different
          functional parts of the server and that each of these can be configured independently.
          If the user is reasonably confident that a problem originates
          in a specific function of the server, or that the problem is related
          to the specific type of operation, they may enable high verbosity
          only for the relevant logger, so limiting the debug messages
          to the required minimum.
108 109 110
        </para>

        <para>
111 112 113 114 115
          The loggers are associated with a particular library or binary
          of Kea. However, each library or binary may (and usually does)
          include multiple loggers. For example, the DHCPv4 server binary
          contains separate loggers for: packet parsing, for dropped packets,
          for callouts etc.
116 117 118
        </para>

        <para>
119 120 121 122 123 124
          The loggers form a hierarchy.  For each program in Kea, there is
          a "root" logger, named after the program (e.g. the root logger for
          kea-dhcp (the DHCPv4 server) is named kea-dhcp4.  All other loggers
          are children of this logger, and are named accordingly, e.g. the
          the allocation engine in the DHCPv4 server logs messages using
          a logger called kea-dhcp4.alloc-engine.
125 126
        </para>

127 128 129 130 131 132 133 134 135
        <para>
          This relationship is important as each child logger derives its
          default configuration from its parent root logger.
          In the typical case, the root logger configuration
          is the only logging configuration specified in the configuration
          file and so applies to all loggers. If an entry is made for
          a given logger, any attributes specified override those of
          the root logger, whereas any not specified are inherited from it.
        </para>
136

137 138 139 140 141 142 143
        <para>
          To illustrate this, suppose you are using the DHCPv4 server
          with the root logger <quote>kea-dhcp4</quote> logging at the
          INFO level. In order to enable DEBUG verbosity for the DHCPv4
          packet drops, you must create configuration entry for the
          logger called <quote>kea-dhcp4.bad-packets</quote> and specify
          severity DEBUG for this logger. All other configuration
Francis Dupont's avatar
Francis Dupont committed
144
          parameters may be omitted for this logger if the logger should
145 146 147
          use the default values specified in the root logger's
          configuration.
        </para>
148

Tomek Mrugalski's avatar
Tomek Mrugalski committed
149
        <!-- we don't support asterisk anymore.
150
        <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
151
          One special case is that of a component name of <quote>*</quote>
152
          (asterisks), which is interpreted as <emphasis>any</emphasis>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
153
          component. You can set global logging options by using this,
154
          including setting the logging configuration for a library
Tomek Mrugalski's avatar
Tomek Mrugalski committed
155
          that is used by multiple daemons (e.g. <quote>*.config</quote>
156
          specifies the configuration library code in whatever
Tomek Mrugalski's avatar
Tomek Mrugalski committed
157
          daemon is using it).
158
        </para> -->
159

160 161 162 163 164
        <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
165 166
          <quote>kea-dhcp4.dhcpsrv</quote>, the DHCPv4 server — and all
          libraries it uses that are not dhcpsrv — will log messages
167 168 169
          according to the configuration in the first entry
          (<quote>kea-dhcp4</quote>).
        </para>
170

171
        <para>
172 173 174 175
          Currently defined loggers are defined in the following table. The
          "Software Package" column of this table specifies whether the particular
          loggers belong to the core Kea code (open source Kea binaries and
          libraries), or hook libraries (open source or premium).
176
        </para>
177

178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193
        <para>
          <table frame="all" xml:id="supported-loggers-list">
            <title>List of loggers supported by Kea servers and hooks libraries
            shipped with Kea and premium packages</title>
            <tgroup cols='3'>
              <colspec colname="logger-name" align="left"/>
              <colspec colname="software-package" align="center"/>
              <colspec colname="description" align="left"/>
              <thead>
                <row>
                  <entry>Logger Name</entry>
                  <entry>Software Package</entry>
                  <entry>Description</entry>
                </row>
              </thead>
              <tbody>
194 195 196 197 198 199 200 201
                <row><entry><command>kea-ctrl-agent</command></entry><entry>core</entry><entry>The root logger for the Control Agent exposing RESTful control API. All components used by the Control Agent inherit the settings from this logger.</entry></row>
                <row><entry><command>kea-ctrl-agent.http</command></entry><entry>core</entry><entry>A logger which outputs log messages related to receiving, parsing and sending HTTP messages.</entry></row>
                <row><entry><command>kea-dhcp4</command></entry><entry>core</entry><entry>The root logger for the DHCPv4 server. All components used by the DHCPv4 server inherit the settings from this logger.</entry></row>
                <row><entry><command>kea-dhcp6</command></entry><entry>core</entry><entry>The root logger for the DHCPv6 server. All components used by the DHCPv6 server inherit the settings from this logger.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.alloc-engine</command></member><member><command>kea-dhcp6.alloc-engine</command></member></simplelist></entry><entry>core</entry><entry>Used by the lease allocation engine, which is responsible for managing leases in the lease database, i.e. create, modify and remove DHCP leases as a result of processing messages from the clients.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.bad-packets</command></member><member><command>kea-dhcp6.bad-packets</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP servers for logging inbound client packets that were dropped or to which the server responded with a DHCPNAK. It allows administrators to configure a separate log output that contains only packet drop and reject entries.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.callouts</command></member><member><command>kea-dhcp6.callouts</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages pertaining to the callouts registration and execution for the particular hook point.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.commands</command></member><member><command>kea-dhcp6.commands</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages relating to the handling of commands received by the the DHCP server over the command channel.</entry></row>
202
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.database</command></member><member><command>kea-dhcp6.database</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages relating to general operations on the relational databases and Cassandra.</entry></row>
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.ddns</command></member><member><command>kea-dhcp6.ddns</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP server to log messages related to the Client FQDN and Hostname option processing. It also includes log messages related to the relevant DNS updates.</entry></row>
                <row><entry><command>kea-dhcp4.dhcp4</command></entry><entry>core</entry><entry>Used by the DHCPv4 server daemon to log basic operations.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.dhcpsrv</command></member><member><command>kea-dhcp6.dhcpsrv</command></member></simplelist></entry><entry>core</entry><entry>The base loggers for the libkea-dhcpsrv library.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.eval</command></member><member><command>kea-dhcp6.eval</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages relating to the client classification expression evaluation code.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.host-cache-hooks</command></member><member><command>kea-dhcp6.host-cache-hooks</command></member></simplelist></entry><entry>libdhcp_host_cache premium hook library</entry><entry>This logger is used to log messages related to operation of the Host Cache Hook Library.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.flex-id-hooks</command></member><member><command>kea-dhcp6.flex-id-hooks</command></member></simplelist></entry><entry>libdhcp_flex_id premium hook library</entry><entry>This logger is used to log messages related to operation of the Flexible Identifiers Hook Library.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.ha-hooks</command></member><member><command>kea-dhcp6.ha-hooks</command></member></simplelist></entry><entry>libdhcp_ha hook library</entry><entry>This logger is used to log messages related to operation of the High Availability Hook Library.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.hooks</command></member><member><command>kea-dhcp6.hooks</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages related to management of hooks libraries, e.g. registration and deregistration of the libraries, and to the initialization of the callouts execution for various hook points within the DHCP server.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.host-cmds-hooks</command></member><member><command>kea-dhcp6.host-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_host_cmds premium hook library</entry><entry>This logger is used to log messages related to operation of the Host Cmds hooks library. In general these will pertain to loading and unloading the library and the execution of commands by the library.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.hosts</command></member><member><command>kea-dhcp6.hosts</command></member></simplelist></entry><entry>core</entry><entry>Used within the libdhcpsrv and it logs messages related to the management of the DHCP host reservations, i.e. retrieval of the reservations and adding new reservations.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.lease-cmds-hooks</command></member><member><command>kea-dhcp6.lease-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_lease_cmds hook library</entry><entry>This logger is used to log messages related to operation of the Lease Cmds hooks library. In general these will pertain to loading and unloading the library and the execution of commands by the library.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.leases</command></member><member><command>kea-dhcp6.leases</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP server to log messages related to the lease allocation. The messages include detailed information about the allocated or offered leases, errors during the lease allocation etc.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.legal-log-hooks</command></member><member><command>kea-dhcp6.legal-log-hooks</command></member></simplelist></entry><entry>libdhcp_legal_log premium hook library</entry><entry>This logger is used to log messages related to operation of the Forensic Logging Hooks Library.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.options</command></member><member><command>kea-dhcp4.options</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP server to log messages related to processing of the options in the DHCP messages, i.e. parsing options, encoding options into on-wire format and packet classification using options contained in the received packets.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.packets</command></member><member><command>kea-dhcp6.packets</command></member></simplelist></entry><entry>core</entry><entry>This logger is mostly used to log messages related to transmission of the DHCP packets, i.e. packet reception and sending a response. Such messages include information about the source and destination IP addresses and interfaces used to transmit packets. The logger is also used to log messages related to subnet selection, as this selection is usually based on the IP addresses, relay addresses and/or interface names, which can be retrieved from the received packet, even before the DHCP message carried in the packet is parsed.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.radius-hooks</command></member><member><command>kea-dhcp6.radius-hooks</command></member></simplelist></entry><entry>libdhcp_radius premium hook library</entry><entry>This logger is used to log messages related to operation of the Radius Hook Library.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.stat-cmds-hooks</command></member><member><command>kea-dhcp6.stat-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_stat_cmds hook library</entry><entry>This logger is used to log messages related to operation of the Stats Cmds hooks library. In general these will pertain to loading and unloading the library and the execution of commands by the library.</entry></row>
                <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.subnet-cmds-hooks</command></member><member><command>kea-dhcp6.subnet-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_subnet_cmds hook library</entry><entry>This logger is used to log messages related to operation of the Subnet Cmds hooks library. In general these will pertain to loading and unloading the library and the execution of commands by the library.</entry></row>
221 222 223 224 225 226 227 228 229
                <row><entry><command>kea-dhcp-ddns</command></entry><entry>core</entry><entry>The root logger for the kea-dhcp-ddns daemon. All components used by this daemon inherit the settings from this logger if there is no specialized logger provided.</entry></row>
                <row><entry><command>kea-dhcp-ddns.dctl</command></entry><entry>core</entry><entry>The logger used by the kea-dhcp-ddns daemon for logging basic information about the process, received signals and triggered reconfigurations.</entry></row>
                <row><entry><command>kea-dhcp-ddns.dhcpddns</command></entry><entry>core</entry><entry>The logger used by the kea-dhcp-ddns daemon for logging events related to DDNS operations.</entry></row>
                <row><entry><command>kea-dhcp-ddns.dhcp-to-d2</command></entry><entry>core</entry><entry>Used by the kea-dhcp-ddns daemon for logging information about events dealing with receiving messages from the DHCP servers and adding them to the queue for processing.</entry></row>
                <row><entry><command>kea-dhcp-ddns.d2-to-dns</command></entry><entry>core</entry><entry>Used by the kea-dhcp-ddns daemon for logging information about events dealing with sending and receiving messages with the DNS servers.</entry></row>
              </tbody>
            </tgroup>
          </table>
        </para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
230

231
        <para>
232
          Note that user-defined hook libraries should not use any of those
233 234
          loggers but should define new loggers with names that correspond to
          the libraries using them. Suppose that the user created the library
235
          called <quote>libdhcp-packet-capture</quote> to dump packets received and
236
          transmitted by the server to the file. The appropriate name for the
237
          logger could be <command>kea-dhcp4.packet-capture-hooks</command>. (Note
238 239 240 241 242 243
          that the hook library implementor only specifies the second part of
          this name, i.e. <quote>packet-capture</quote>. The first part is a
          root logger name and is prepended by the Kea logging system.) It is
          also important to note that since this new logger is a child of a root
          logger, it inherits the configuration from the root logger, something
          that can be overridden by an entry in the configuration file.
244 245
        </para>

246 247 248 249 250 251 252
        <para>
          Additional loggers may be defined in future versions of Kea. 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>
253

254 255
      <section>
        <title>severity (string)</title>
256
        <para>
257 258 259
          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 severity):
260 261 262 263
        </para>

        <itemizedlist>
          <listitem>
264 265 266 267
            <simpara>
              FATAL - associated with messages generated by a condition that is
              so serious that the server cannot continue executing.
            </simpara>
268 269 270
          </listitem>

          <listitem>
271 272 273 274 275
            <simpara>
              ERROR- associated with messages generated by an error condition.
              The server will continue executing, but the results may not be as
              expected.
            </simpara>
276 277 278
          </listitem>

          <listitem>
279 280 281 282
            <simpara>
              WARN - indicates an out of the ordinary condition.  However, the
              server will continue executing normally.
            </simpara>
283 284 285
          </listitem>

          <listitem>
286 287 288
            <simpara>
              INFO - an informational message marking some event.
            </simpara>
289 290 291
          </listitem>

          <listitem>
292 293 294
            <simpara>
              DEBUG - messages produced for debugging purposes.
            </simpara>
295 296 297 298
          </listitem>
        </itemizedlist>

        <para>
299 300 301 302 303
          When the severity of a logger is set to one of these values, it will
          only log messages of that severity and above (e.g. setting the logging
          severity to INFO will log INFO, WARN, ERROR and FATAL messages).  The
          severity may also be set to NONE, in which case all messages from that
          logger are inhibited.
304 305
        </para>

306 307 308
        <note>
          <para>
            The keactrl tool, described in <xref linkend="keactrl"/>, can be
309 310 311 312 313 314 315 316
            configured to start the servers in the verbose mode. If this is the
            case, the settings of the logging severity in the configuration file
            will have no effect, i.e. the servers will use logging severity of
            DEBUG regardless of the logging settings specified in the
            configuration file. If you need to control severity via
            configuration file, please make sure that the
            <parameter>kea_verbose</parameter> value is set to "no" within the
            keactrl configuration.
317 318
          </para>
        </note>
319
      </section>
320

321 322
      <section>
        <title>debuglevel (integer)</title>
323
        <para>
324 325 326 327
          When a logger's severity is set to DEBUG, this value specifies what
          level of debug messages should be printed. It ranges from 0 (least
          verbose) to 99 (most verbose). If severity for the logger is not
          DEBUG, this value is ignored.
328 329 330 331
        </para>
      </section>

      <section>
332
        <title>output_options (list)</title>
333
        <para>
334 335 336
          Each logger can have zero or more <option>output_options</option>.
          These specify where log messages are sent. These are explained in
          detail below.
337 338 339
        </para>

        <section>
340
          <title>output (string)</title>
341
          <para>
342 343 344 345 346 347 348
            This value determines the type of output. There are several special
            values allowed here: <command>stdout</command> (messages are printed
            on standard output), <command>stderr</command> (messages are printed
            on stderr), <command>syslog</command> (messages are logged to syslog
            using default name, <command>syslog:name</command> (messages are
            logged to syslog using specified name). Any other value is
            interpreted as a filename to which messages should be written.
349 350 351 352 353 354
          </para>
        </section>

        <section>
          <title>flush (true of false)</title>
          <para>
355 356 357 358
            Flush buffers after each log message. Doing this will reduce
            performance but will ensure that if the program terminates
            abnormally, all messages up to the point of termination are output.
            The default is "true".
359
          </para>
360
        </section>
361 362 363 364

        <section>
          <title>maxsize (integer)</title>
          <para>
365 366 367
            Only relevant when the destination is a file. This is maximum size
            in bytes that a log file may reach.  When the maximum size is
            reached, the file is renamed and a new file opened. For example,
368
            a ".1" is appended to the name — if a ".1" file exists, it
369
            is renamed ".2", etc. This is referred to as rotation.
370 371
          </para>
          <para>
372 373
            The default value is 10240000 (10MB).  The smallest value that may
            be specified without disabling rotation is 204800. Any value less than
374
            this, including 0, disables rotation.
375 376 377
          </para>
          <note>
            <simpara>
378 379 380 381 382 383 384 385 386 387 388
              Due to a limitation of the underlying logging library (log4cplus),
              rolling over the log files (from ".1" to ".2", etc) may show odd
              results: There can be multiple small files at the timing of roll
              over.  This can happen when multiple processes try to roll over
              the files simultaneously.  Version 1.1.0 of log4cplus solved this
              problem, so if this version or later of log4cplus is used to
              build Kea, it should not happen.  Even for older versions it is
              normally expected to happen rarely unless the log messages are
              produced very frequently by multiple different processes.
            </simpara>
          </note>
389 390 391 392 393
        </section>

        <section>
          <title>maxver (integer)</title>
          <para>
394 395 396 397 398 399 400
            Only relevant when the destination is file and rotation is enabled
            (i.e. maxsize is large enough).  This is maximum number of rotated
            versions that will be kept. Once that number of files has been
            reached, the oldest file, "log-name.maxver", will be discarded
            each time the log rotates. In other words, at most there will be
            the active log file plus maxver rotated files.  The minimum and
            default value is 1.
401 402 403 404 405
          </para>
        </section>
      </section>

      <section>
406
        <title>Example Logger Configurations</title>
407
        <para>
408 409
          In this example we want to set the global logging to write to the
          console using standard output.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
410 411
        </para>

412
<screen><userinput>"Logging": {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
413 414
    "loggers": [
        {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
415
            "name": "kea-dhcp4",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
416 417 418 419
            "output_options": [
                {
                    "output": "stdout"
                }
420
            ],
Tomek Mrugalski's avatar
Tomek Mrugalski committed
421 422 423
            "severity": "WARN"
        }
    ]
424
}</userinput> </screen>
425

426 427 428 429 430 431
        <para>
          In this second example, we want to store debug log messages in a file
          that is at most 2MB and keep up to 8 copies of old logfiles.  Once the
          logfile grows to 2MB, it will be renamed and a new file file be
          created.
        </para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
432

433
<screen><userinput>"Logging": {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
434 435
    "loggers": [
        {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
436
            "name": "kea-dhcp6",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
437 438 439 440 441
            "output_options": [
                {
                    "output": "/var/log/kea-debug.log",
                    "maxver": 8,
                    "maxsize": 204800,
442
                    "flush": true
Tomek Mrugalski's avatar
Tomek Mrugalski committed
443
                }
444
            ],
Tomek Mrugalski's avatar
Tomek Mrugalski committed
445 446 447 448 449
            "severity": "DEBUG",
            "debuglevel": 99
        }
   ]
}</userinput></screen>
450 451 452 453
      </section>

    </section>

454
    <section xml:id="logging-message-format">
455 456
      <title>Logging Message Format</title>
      <para>
457 458 459 460
        Each message written  to the configured logging destinations comprises a
        number of components that identify the origin of the message and, if the
        message indicates a problem, information about the problem that may be
        useful in fixing it.
461 462 463
      </para>

      <para>
464 465 466
        Consider the message below logged to a file:

<screen>2014-04-11 12:58:01.005 INFO  [kea-dhcp4.dhcpsrv/27456]
467 468 469 470
    DHCPSRV_MEMFILE_DB opening memory file lease database: type=memfile universe=4</screen>
      </para>

      <para>
471 472 473 474
        Note: the layout of messages written to the system logging file (syslog)
        may be slightly different.  This message has been split across two lines
        here for display reasons; in the logging file, it will appear on one
        line.
475 476 477 478 479
      </para>

      <para>
        The log message comprises a number of components:

480 481 482
       <variablelist>
         <varlistentry>
           <term>2014-04-11 12:58:01.005</term>
483
<!-- TODO: timestamp repeated even if using syslog? -->
484 485 486 487 488
           <listitem>
             <para>
               The date and time at which the message was generated.
              </para>
            </listitem>
489 490 491
          </varlistentry>

          <varlistentry>
492 493 494 495 496 497
            <term>INFO</term>
            <listitem>
              <para>
                The severity of the message.
              </para>
            </listitem>
498 499 500
          </varlistentry>

          <varlistentry>
501 502 503 504 505 506 507 508 509 510 511 512
            <term>[kea-dhcp4.dhcpsrv/27456]</term>
            <listitem>
              <para>
                The source of the message.  This comprises two elements: the Kea
                process generating the message (in this case,
                <command>kea-dhcp4</command>) and the component within the
                program from which the message originated
                (<command>dhcpsrv</command>, which is the name of the common
                library used by DHCP server implementations). The number after
                the slash is a process id (pid).
              </para>
            </listitem>
513 514 515
          </varlistentry>

          <varlistentry>
516 517 518 519 520
            <term>DHCPSRV_MEMFILE_DB</term>
            <listitem>
              <para>
                The message identification.  Every message in Kea has a unique
                identification, which can be used as an index into the
521 522
                <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="kea-messages.html"><citetitle>Kea Messages
                Manual</citetitle></link>
523
                (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://oldkea.isc.org/docs/kea-messages.html">http://oldkea.isc.org/docs/kea-messages.html</uri>)
524 525 526
                from which more information can be obtained.
              </para>
            </listitem>
527 528 529
          </varlistentry>

          <varlistentry>
530 531 532 533 534 535 536 537 538 539
            <term>opening memory file lease database: type=memfile universe=4</term>
            <listitem>
              <para>
                A brief description.  Within this text, information relating to
                the condition that caused the message to be logged will be
                included.  In this example, the information is logged that the
                in-memory lease database backend will be used to store DHCP
                leases.
              </para>
            </listitem>
540
          </varlistentry>
541
        </variablelist>
542 543 544
      </para>
    </section>

545
    <section xml:id="logging-during-startup">
546
      <title>Logging During Kea Startup</title>
547
      <para>
548 549
        The logging configuration is specified in the configuration file.
        However, when Kea starts, the file is not read until some way into the
550 551 552 553 554 555
        initialization process.  Prior to that, the logging settings are set to
        default values, although it is possible to modify some aspects of the
        settings by means of environment variables. Note that in the absence of
        any logging configuration in the configuration file, the settings of
        (possibly modified) default configuration will persist while the program
        is running.
556 557
      </para>
      <para>
558 559
        The following environment variables can be used to control the behavior
        of logging during startup:
560 561
      </para>

562 563
      <variablelist>
        <varlistentry>
564
          <term>KEA_LOCKFILE_DIR</term>
565 566
          <listitem>
            <para>
567
              Specifies a directory where the logging system should create its
568 569
              lock file. If not specified, it is
              <replaceable>prefix</replaceable>/var/run/kea, where
570 571 572 573 574 575 576
              <replaceable>prefix</replaceable> defaults to /usr/local.  This
              variable must not end with a slash. There is one special value:
              "none", which instructs Kea to not create lock file at all. This
              may cause issues if several processes log to the same file.
            </para>
          </listitem>
        </varlistentry>
577

578
        <varlistentry>
579
          <term>KEA_LOGGER_DESTINATION</term>
580 581
          <listitem>
            <para>
582
              Specifies logging output. There are several special values.
583
              <variablelist>
584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613
                <varlistentry>
                  <term>stdout</term>
                  <listitem>
                    <para>
                      Log to standard output.
                    </para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term>stderr</term>
                  <listitem>
                    <para>
                      Log to standard error.
                    </para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term>syslog<optional>:<replaceable>fac</replaceable></optional></term>
                  <listitem>
                    <para>
                      Log via syslog. The optional
                      <replaceable>fac</replaceable> (which is separated from
                      the word "syslog" by a colon) specifies the facility to be
                      used for the log messages. Unless specified, messages will
                      be logged using the facility "local0".
                    </para>
                  </listitem>
                </varlistentry>
614
              </variablelist>
615 616 617 618 619 620
              Any other value is treated as a name of the output file. If not
              specified otherwise, Kea will log to standard output.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
621
    </section>
622 623
  </section>
</chapter>