logging.xml 23.3 KB
Newer Older
1
2
3
4
5
6
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash  "&#x2014;" >
]>

Tomek Mrugalski's avatar
Tomek Mrugalski committed
7
8
9
10
11
12
13
14
15
16
17
18
  <!-- 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
    -->

19
20
21
22
  <chapter id="logging">
    <title>Logging</title>

    <section>
23
      <title>Logging Configuration</title>
24
25

      <para>
26
27
28
        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
Tomek Mrugalski's avatar
Tomek Mrugalski committed
29
        which log messages are needed and which are not and configure your
30
        logging appropriately. For example, debug level messages can be safely
Tomek Mrugalski's avatar
Tomek Mrugalski committed
31
32
        ignored in a typical deployment. They are, however, very useful when
        debugging a problem.
33
      </para>
34

35
      <para>
36
        The logging system in Kea is configured through the
Tomek Mrugalski's avatar
Tomek Mrugalski committed
37
        <replaceable>Logging</replaceable> structure in your configuration
38
        file. All daemons (e.g. DHCPv4 and DHCPv6 servers) will use the
Tomek Mrugalski's avatar
Tomek Mrugalski committed
39
        configuration in the <replaceable>Logging</replaceable> structure to see
40
        what should be logged and to where. This allows for sharing identical
Tomek Mrugalski's avatar
Tomek Mrugalski committed
41
        logging configuration between daemons.
42
43
44
45
46
47
      </para>

      <section>
        <title>Loggers</title>

        <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
48
49
          Within Kea, a message is logged through an entity
          called a "logger". Different parts of the code log messages
50
          through different loggers, and each logger can be configured
Tomek Mrugalski's avatar
Tomek Mrugalski committed
51
52
53
          independently of one another. For example there are different
          components that deal with hooks ("hooks" logger) and with
          DHCP engine ("dhcpsrv" logger).
54
55
56
        </para>

        <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
57
58
          In the Logging structure in a configuration file you can
          specify the configuration for zero or more loggers. If there are
59
          no loggers specified, the code will use default values which
Tomek Mrugalski's avatar
Tomek Mrugalski committed
60
61
62
63
          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. -->
64
65
66
67
68
69
70
71
72
73
74
75
76
77
        </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>
78
79
            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
Tomek Mrugalski's avatar
Tomek Mrugalski committed
80
81
82
83
84
            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).
Tomek Mrugalski's avatar
Tomek Mrugalski committed
85
          </para>
86
87

          <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
88
89
90
            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
91
92
93
            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
Tomek Mrugalski's avatar
Tomek Mrugalski committed
94
            given for the whole daemon.
95
          </para>
96

97
98
99
          <para>
            To illustrate this, suppose you want the dhcpsrv library
            to log messages of severity DEBUG, and the rest of the
Tomek Mrugalski's avatar
Tomek Mrugalski committed
100
            DHCPv4 server code to log messages of severity INFO. To achieve
101
102
103
104
            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,
Tomek Mrugalski's avatar
Tomek Mrugalski committed
105
            they will use the configuration for the daemon
106
107
            (<quote>kea-dhcp4</quote>), so giving the desired behavior.
          </para>
108

Tomek Mrugalski's avatar
Tomek Mrugalski committed
109
        <!-- we don't support asterisk anymore.
110
        <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
111
          One special case is that of a component name of <quote>*</quote>
112
          (asterisks), which is interpreted as <emphasis>any</emphasis>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
113
          component. You can set global logging options by using this,
114
          including setting the logging configuration for a library
Tomek Mrugalski's avatar
Tomek Mrugalski committed
115
          that is used by multiple daemons (e.g. <quote>*.config</quote>
116
          specifies the configuration library code in whatever
Tomek Mrugalski's avatar
Tomek Mrugalski committed
117
          daemon is using it).
118
        </para> -->
119

120
121
122
123
124
          <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
Tomek Mrugalski's avatar
Tomek Mrugalski committed
125
            <quote>kea-dhcp4.dhcpsrv</quote>, the DHCPv4 server &mdash; and all
126
127
128
129
            libraries it uses that are not dhcpsrv &mdash; will log messages
            according to the configuration in the first entry
            (<quote>kea-dhcp4</quote>).
          </para>
130

131
          <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
132
            One final note about the naming. When specifying the daemon name
133
            within a logger, use the name of the binary file,
Tomek Mrugalski's avatar
Tomek Mrugalski committed
134
135
            e.g. <quote>kea-dhcp4</quote> for the DHCPv4 server,
            <quote>kea-dhcp6</quote> for the DHCPv6 server, etc. When the
136
137
138
139
140
141
142
143
144
            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>
145

146
147
148
          <para>
            Currently defined loggers are:
          </para>
149

Tomek Mrugalski's avatar
Tomek Mrugalski committed
150
        <itemizedlist>
151
152
153
154
155
156
          <listitem>
            <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>
157
158
          <listitem>
            <simpara><command>kea-dhcp4.bad_packet</command> - this is the
159
            logger used by the DHCPv4 server deamon for logging inbound client
160
161
162
163
            packets that were dropped or to which the server responded with a
            NAK.  The allows adminstrators to configure a separate log
            output that contains only packet drop and reject entries.</simpara>
          </listitem>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
164
          <listitem>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
165
            <simpara><command>kea-dhcp4.dhcp4</command> - this is the logger
166
167
            used solely by the DHCPv4 server deamon. This logger does not
            specify logging settings for libraries used by the deamon.</simpara>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
168
169
          </listitem>
          <listitem>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
170
171
172
173
            <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>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
174
175
          </listitem>
          <listitem>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
176
177
178
            <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>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
179
180
          </listitem>
          <listitem>
181
182
183
184
185
186
187
188
189
            <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><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>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
190
191
          </listitem>
          <listitem>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
192
193
194
195
            <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>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
196
          </listitem>
197
          <listitem>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
198
199
200
            <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>
201
202
          </listitem>
          <listitem>
203
204
205
206
207
208
209
210
211
            <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>
212
          </listitem>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
213
214
        </itemizedlist>

215
216
217
218
        <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>
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
        </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
          severity):
        </para>

        <itemizedlist>
          <listitem>
            <simpara> FATAL </simpara>
          </listitem>

          <listitem>
            <simpara> ERROR </simpara>
          </listitem>

          <listitem>
            <simpara> WARN </simpara>
          </listitem>

          <listitem>
            <simpara> INFO </simpara>
          </listitem>

          <listitem>
            <simpara> DEBUG </simpara>
          </listitem>
        </itemizedlist>

        <para>

          When the severity of a logger is set to one of these
          values, it will only log messages of that severity, and
          the severities above it. The severity may also be set to
          NONE, in which case all messages from that logger are
          inhibited.

<!-- TODO: worded wrong? If I set to INFO, why would it show DEBUG which is literally below in that list? -->

        </para>

        </section>

        <section>
          <title>output_options (list)</title>

        <para>

          Each logger can have zero or more
          <option>output_options</option>. These specify where log
274
          messages are sent. These are explained in detail below.
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356

        </para>

        <para>

          The other options for a logger are:

        </para>

        </section>

        <section>
          <title>debuglevel (integer)</title>

        <para>

          When a logger's severity is set to DEBUG, this value
          specifies what debug messages should be printed. It ranges
          from 0 (least verbose) to 99 (most verbose).
        </para>


<!-- TODO: complete this sentence:

          The general classification of debug message types is

TODO; there's a ticket to determine these levels, see #1074

 -->

        <para>

          If severity for the logger is not DEBUG, this value is ignored.

        </para>

        </section>
      </section>

      <section>
        <title>Output Options</title>

        <para>

          The main settings for an output option are the
          <option>destination</option> and a value called
          <option>output</option>, the meaning of which depends on
          the destination that is set.

        </para>

        <section>
          <title>destination (string)</title>

          <para>

            The destination is the type of output. It can be one of:

          </para>

          <itemizedlist>

            <listitem>
              <simpara> console </simpara>
          </listitem>

            <listitem>
              <simpara> file </simpara>
          </listitem>

            <listitem>
              <simpara> syslog </simpara>
            </listitem>

          </itemizedlist>

        </section>

        <section>
          <title>output (string)</title>

        <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
357
358
359
360
361
362
363
          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 that the logs should be written to.
364
365
366
367
368
369
370
371
        </para>

        <para>

          The other options for <option>output_options</option> are:

        </para>

372
        <!-- configuration of flush is not supported yet.
373
374
375
376
377
378
379
380
381
382
        <section>
          <title>flush (true of false)</title>

          <para>
            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.
          </para>

Tomek Mrugalski's avatar
Tomek Mrugalski committed
383
        </section> -->
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425

        <section>
          <title>maxsize (integer)</title>

          <para>
            Only relevant when destination is file, this is maximum
            file size of output files in bytes. When the maximum
            size is reached, the file is renamed and a new file opened.
            (For example, a ".1" is appended to the name &mdash;
            if a ".1" file exists, it is renamed ".2",
            etc.)
          </para>

          <para>
            If this is 0, no maximum file size is used.
          </para>

          <note>
            <simpara>
	      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 or higher version of log4cplus is used to build
	      Kea, it shouldn't 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>

        </section>

        <section>
          <title>maxver (integer)</title>

          <para>
            Maximum number of old log files to keep around when
            rolling the output file. Only relevant when
Tomek Mrugalski's avatar
Tomek Mrugalski committed
426
            <option>output</option> is <quote>file</quote>.
427
428
429
430
431
432
433
434
435
          </para>

        </section>

      </section>

      </section>

      <section>
436
        <title>Example Logger Configurations</title>
437
438
439

        <para>
          In this example we want to set the global logging to
Tomek Mrugalski's avatar
Tomek Mrugalski committed
440
441
442
443
444
445
446
          write to the console using standard output.
        </para>

<screen><userinput>
"Logging": {
    "loggers": [
        {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
447
            "name": "kea-dhcp4",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
448
449
450
451
            "output_options": [
                {
                    "output": "stdout"
                }
452
            ],
Tomek Mrugalski's avatar
Tomek Mrugalski committed
453
454
455
456
457
            "severity": "WARN"
        }
    ]
}
</userinput>
458
459
</screen>

Tomek Mrugalski's avatar
Tomek Mrugalski committed
460
461
462
463
464
465
466
467
468
<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>

<screen><userinput>
"Logging": {
    "loggers": [
        {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
469
            "name": "kea-dhcp6",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
470
471
472
473
474
475
476
            "output_options": [
                {
                    "output": "/var/log/kea-debug.log",
                    "maxver": 8,
                    "maxsize": 204800,
                    "destination": "file"
                }
477
            ],
Tomek Mrugalski's avatar
Tomek Mrugalski committed
478
479
480
481
482
            "severity": "DEBUG",
            "debuglevel": 99
        }
   ]
}</userinput></screen>
483
484
485
486
      </section>

    </section>

487
    <section id="logging-message-format">
488
489
490
491
492
493
494
495
496
497
498
499
      <title>Logging Message Format</title>

      <para>
          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.
      </para>

      <para>
          Consider the message below logged to a file:
500
          <screen>2014-04-11 12:58:01.005 INFO  [kea-dhcp4.dhcpsrv/27456]
501
502
503
504
505
506
507
    DHCPSRV_MEMFILE_DB opening memory file lease database: type=memfile universe=4</screen>
      </para>

      <para>
        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
508
        logging file, it will appear on one line.
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
      </para>

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

          <variablelist>
          <varlistentry>
          <term>2014-04-11 12:58:01.005</term>
<!-- TODO: timestamp repeated even if using syslog? -->
          <listitem><para>
              The date and time at which the message was generated.
          </para></listitem>
          </varlistentry>

          <varlistentry>
          <term>INFO</term>
          <listitem><para>
              The severity of the message.
          </para></listitem>
          </varlistentry>

          <varlistentry>
531
          <term>[kea-dhcp4.dhcpsrv/27456]</term>
532
          <listitem><para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
533
            The source of the message.  This comprises two elements:
534
            the Kea process generating the message (in this
Tomek Mrugalski's avatar
Tomek Mrugalski committed
535
            case, <command>kea-dhcp4</command>) and the component
536
537
            within the program from which the message originated
            (which is the name of the common library used by DHCP server
538
539
            implementations). The number after the slash is a process id
            (pid).
540
541
542
543
544
545
546
547
548
          </para></listitem>
          </varlistentry>

          <varlistentry>
          <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 <ulink
549
            url="kea-messages.html"><citetitle>Kea Messages
550
            Manual</citetitle></ulink> (<ulink
551
            url="http://kea.isc.org/docs/kea-messages.html"
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
            />) from which more information can be obtained.
          </para></listitem>
          </varlistentry>

          <varlistentry>
          <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>
          </varlistentry>
          </variablelist>
      </para>

    </section>

571
    <section>
572
      <title>Logging During Kea Startup</title>
573
574

      <para>
575
576
577
578
579
580
581
582
583
584
585
586
        The logging configuration is specified in the configuration file.
        However, when Kea starts, the file is not read until some way into the
        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.
      </para>
      <para>
        The following environment variables can be used to control the
        behavio of logging during startup:
587
588
589
590
591
592
      </para>

          <variablelist>
          <varlistentry>
          <term>KEA_LOCKFILE_DIR</term>
          <listitem><para>
593
              Specifies a directory where the logging system should create its
594
595
596
597
              lock file. If not specified, it is
              <replaceable>prefix</replaceable>/var/run/kea, where
              <replaceable>prefix</replaceable> defaults to /usr/local.
              This variable must not end
598
599
600
601
602
603
604
605
606
607
              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>

          <varlistentry>
          <term>KEA_LOGGER_DESTINATION</term>
          <listitem><para>
              Specifies logging output. There are several special values.
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
              <variablelist>
                  <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>
              </variablelist>
              Any other value is treated as a name
635
636
637
638
639
640
641
642
              of the output file. If not specified otherwise, Kea will log to
              standard output.
          </para></listitem>
          </varlistentry>

          </variablelist>
    </section>

643
  </chapter>