logging.xml 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  3. "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
  4. <!ENTITY mdash "&#x2014;" >
  5. ]>
  6. <chapter id="logging">
  7. <title>Logging</title>
  8. <section>
  9. <title>Logging configuration</title>
  10. <para>
  11. During its operation Kea may produce many messages. They differ in
  12. severity (some are more important than others) and source (some are
  13. produced by specific components, e.g. hooks). It is useful to understand
  14. which log messages are needed and which are not. For example debug level
  15. messages can be safely ignored in a typical deployment. They are,
  16. however, very useful when debugging a problem.
  17. </para>
  18. <para>
  19. The logging system in Kea is configured through the
  20. <replaceable>Logging</replaceable> module. All modules will look at the
  21. configuration in <replaceable>Logging</replaceable> to see what should
  22. be logged and to where. This allows sharing identical logging
  23. configuration between components.
  24. </para>
  25. <section>
  26. <title>Loggers</title>
  27. <para>
  28. Within Kea, a message is logged through a component
  29. called a "logger". Different parts of log messages
  30. through different loggers, and each logger can be configured
  31. independently of one another.
  32. </para>
  33. <para>
  34. In the Logging module, you can specify the configuration
  35. for zero or more loggers; any that are not specified will
  36. take appropriate default values.
  37. </para>
  38. <para>
  39. The three most important elements of a logger configuration
  40. are the <option>name</option> (the component that is
  41. generating the messages), the <option>severity</option>
  42. (what to log), and the <option>output_options</option>
  43. (where to log).
  44. </para>
  45. <section>
  46. <title>name (string)</title>
  47. <para>
  48. Each logger in the system has a name, the name being that of the
  49. component binary file using it to log messages. For instance, if you
  50. want to configure logging for the Dhcp4 module, you add an entry for
  51. a logger named <quote>kea-dhcp4</quote>. This configuration will
  52. then be used by the loggers in the Dhcp4 module, and all the
  53. libraries used by it (unless a library defines its own logger).
  54. </para>
  55. <!-- TODO: later we will have a way to know names of all modules -->
  56. <para>
  57. If you want to specify logging for one specific library within the
  58. module, you set the name to
  59. <replaceable>module.library</replaceable>. For example, the logger
  60. used by the code from libdhcpsrv used in kea-dhcp4 binary has the
  61. full name of <quote>kea-dhcp4.dhcpsrv</quote>. If there is no entry
  62. in Logging for a particular library, it will use the configuration
  63. given for the module.
  64. </para>
  65. <para>
  66. To illustrate this, suppose you want the dhcpsrv library
  67. to log messages of severity DEBUG, and the rest of the
  68. Dhcp4 code to log messages of severity INFO. To achieve
  69. this you specify two loggers, one with the name
  70. <quote>kea-dhcp4</quote> and severity INFO, and one with
  71. the name <quote>kea-dhcp4.dhcpsrv</quote> with severity
  72. DEBUG. As there are no entries for other libraries,
  73. they will use the configuration for the module
  74. (<quote>kea-dhcp4</quote>), so giving the desired behavior.
  75. </para>
  76. <!--
  77. <para>
  78. One special case is that of a module name of <quote>*</quote>
  79. (asterisks), which is interpreted as <emphasis>any</emphasis>
  80. module. You can set global logging options by using this,
  81. including setting the logging configuration for a library
  82. that is used by multiple modules (e.g. <quote>*.config</quote>
  83. specifies the configuration library code in whatever
  84. module is using it).
  85. </para> -->
  86. <para>
  87. If there are multiple logger specifications in the configuration
  88. that might match a particular logger, the specification with the
  89. more specific logger name takes precedence. For example, if there
  90. are entries for both <quote>kea-dhcp4</quote> and
  91. <quote>kea-dhcp4.dhcpsrv</quote>, the Dhcp4 module &mdash; and all
  92. libraries it uses that are not dhcpsrv &mdash; will log messages
  93. according to the configuration in the first entry
  94. (<quote>kea-dhcp4</quote>).
  95. </para>
  96. <para>
  97. One final note about the naming. When specifying the module name
  98. within a logger, use the name of the binary file,
  99. e.g. <quote>kea-dhcp4</quote> for the DHCPv4 module,
  100. <quote>kea-dhcp6</quote> for the DHCPv6 module, etc. When the
  101. message is logged, the message will include the name of the process
  102. (e.g. <quote>kea-dhcp4</quote>) followed by the specific component
  103. in that process, e.g. <quote>hooks</quote>. It is possible to
  104. specify either just the process name (<quote>kea-dhcp4</quote>, will
  105. apply to everything logged within that process) or process name
  106. followed by specific logger,
  107. e.g. <quote>kea-dhcp4.hooks</quote>. That will apply only to
  108. messages originating from that component.
  109. </para>
  110. <para>
  111. Currently defined loggers are:
  112. </para>
  113. <itemizedlist>
  114. <listitem>
  115. <simpara>kea-dhcp4.dhcp4</simpara>
  116. </listitem>
  117. <listitem>
  118. <simpara>kea-dhcp4.dhcpsrv</simpara>
  119. </listitem>
  120. <listitem>
  121. <simpara>kea-dhcp4.hooks</simpara>
  122. </listitem>
  123. <listitem>
  124. <simpara>kea-dhcp6.dhcp6</simpara>
  125. </listitem>
  126. <listitem>
  127. <simpara>kea-dhcp6.dhcpsrv</simpara>
  128. </listitem>
  129. <listitem>
  130. <simpara>kea-dhcp6.hooks</simpara>
  131. </listitem>
  132. <listitem>
  133. <simpara>kea-dhcp-ddns.dhcpddns</simpara>
  134. </listitem>
  135. </itemizedlist>
  136. <para>Additional loggers may be defined in the future. The easiest
  137. way to find out the logger name is to configure all logging to go
  138. to a single destination and look for specific logger names. See
  139. <xref linkend="logging-message-format"/> for details.</para>
  140. </section>
  141. <section>
  142. <title>severity (string)</title>
  143. <para>
  144. This specifies the category of messages logged.
  145. Each message is logged with an associated severity which
  146. may be one of the following (in descending order of
  147. severity):
  148. </para>
  149. <itemizedlist>
  150. <listitem>
  151. <simpara> FATAL </simpara>
  152. </listitem>
  153. <listitem>
  154. <simpara> ERROR </simpara>
  155. </listitem>
  156. <listitem>
  157. <simpara> WARN </simpara>
  158. </listitem>
  159. <listitem>
  160. <simpara> INFO </simpara>
  161. </listitem>
  162. <listitem>
  163. <simpara> DEBUG </simpara>
  164. </listitem>
  165. </itemizedlist>
  166. <para>
  167. When the severity of a logger is set to one of these
  168. values, it will only log messages of that severity, and
  169. the severities above it. The severity may also be set to
  170. NONE, in which case all messages from that logger are
  171. inhibited.
  172. <!-- TODO: worded wrong? If I set to INFO, why would it show DEBUG which is literally below in that list? -->
  173. </para>
  174. </section>
  175. <section>
  176. <title>output_options (list)</title>
  177. <para>
  178. Each logger can have zero or more
  179. <option>output_options</option>. These specify where log
  180. messages are sent to. These are explained in detail below.
  181. </para>
  182. <para>
  183. The other options for a logger are:
  184. </para>
  185. </section>
  186. <section>
  187. <title>debuglevel (integer)</title>
  188. <para>
  189. When a logger's severity is set to DEBUG, this value
  190. specifies what debug messages should be printed. It ranges
  191. from 0 (least verbose) to 99 (most verbose).
  192. </para>
  193. <!-- TODO: complete this sentence:
  194. The general classification of debug message types is
  195. TODO; there's a ticket to determine these levels, see #1074
  196. -->
  197. <para>
  198. If severity for the logger is not DEBUG, this value is ignored.
  199. </para>
  200. </section>
  201. <section>
  202. <title>additive (true or false)</title>
  203. <para>
  204. If this is true, the <option>output_options</option> from
  205. the parent will be used. For example, if there are two
  206. loggers configured; <quote>Dhcp4</quote> and
  207. <quote>Dhcp4.dhcpsrv</quote>, and <option>additive</option>
  208. is true in the second, it will write the log messages
  209. not only to the destinations specified for
  210. <quote>Dhcp4.dhcpsrv</quote>, but also to the destinations
  211. as specified in the <option>output_options</option> in
  212. the logger named <quote>Dhcp4</quote>.
  213. </para>
  214. </section>
  215. </section>
  216. <section>
  217. <title>Output Options</title>
  218. <para>
  219. The main settings for an output option are the
  220. <option>destination</option> and a value called
  221. <option>output</option>, the meaning of which depends on
  222. the destination that is set.
  223. </para>
  224. <section>
  225. <title>destination (string)</title>
  226. <para>
  227. The destination is the type of output. It can be one of:
  228. </para>
  229. <itemizedlist>
  230. <listitem>
  231. <simpara> console </simpara>
  232. </listitem>
  233. <listitem>
  234. <simpara> file </simpara>
  235. </listitem>
  236. <listitem>
  237. <simpara> syslog </simpara>
  238. </listitem>
  239. </itemizedlist>
  240. </section>
  241. <section>
  242. <title>output (string)</title>
  243. <para>
  244. This value determines the type of output. There are several
  245. special values allowed here: <command>stdout</command> (messages
  246. are printed on standard output), <command>stderr</command>
  247. (messages are printed on stderr), <command>syslog</command> (messages
  248. are logged to syslog using default name, <command>syslog:name</command>
  249. (messages are logged to syslog using specified name). Any other
  250. value is interpreted as a filename that the logs should be written to.
  251. </para>
  252. <para>
  253. The other options for <option>output_options</option> are:
  254. </para>
  255. <!-- configuration of flush is not supported yet.
  256. <section>
  257. <title>flush (true of false)</title>
  258. <para>
  259. Flush buffers after each log message. Doing this will
  260. reduce performance but will ensure that if the program
  261. terminates abnormally, all messages up to the point of
  262. termination are output.
  263. </para>
  264. </section> -->
  265. <section>
  266. <title>maxsize (integer)</title>
  267. <para>
  268. Only relevant when destination is file, this is maximum
  269. file size of output files in bytes. When the maximum
  270. size is reached, the file is renamed and a new file opened.
  271. (For example, a ".1" is appended to the name &mdash;
  272. if a ".1" file exists, it is renamed ".2",
  273. etc.)
  274. </para>
  275. <para>
  276. If this is 0, no maximum file size is used.
  277. </para>
  278. <note>
  279. <simpara>
  280. Due to a limitation of the underlying logging library
  281. (log4cplus), rolling over the log files (from ".1" to
  282. ".2", etc) may show odd results: There can be
  283. multiple small files at the timing of roll over. This
  284. can happen when multiple processes try to roll
  285. over the files simultaneously.
  286. Version 1.1.0 of log4cplus solved this problem, so if
  287. this or higher version of log4cplus is used to build
  288. Kea, it shouldn't happen. Even for older versions
  289. it is normally expected to happen rarely unless the log
  290. messages are produced very frequently by multiple
  291. different processes.
  292. </simpara>
  293. </note>
  294. </section>
  295. <section>
  296. <title>maxver (integer)</title>
  297. <para>
  298. Maximum number of old log files to keep around when
  299. rolling the output file. Only relevant when
  300. <option>output</option> is <quote>file</quote>.
  301. </para>
  302. </section>
  303. </section>
  304. </section>
  305. <section>
  306. <title>Example Logger configurations</title>
  307. <para>
  308. In this example we want to set the global logging to
  309. write to the console using standard output.
  310. </para>
  311. <screen><userinput>
  312. "Logging": {
  313. "loggers": [
  314. {
  315. "name": "kea-dhcp4",
  316. "output_options": [
  317. {
  318. "output": "stdout"
  319. }
  320. ],
  321. "severity": "WARN"
  322. }
  323. ]
  324. }
  325. </userinput>
  326. </screen>
  327. <para>In this second example, we want to store debug log messages
  328. in a file that is at most 2MB and keep up to 8 copies of old logfiles.
  329. Once the logfile grows to 2MB, it will be renamed and a new file
  330. file be created.</para>
  331. <screen><userinput>
  332. "Logging": {
  333. "loggers": [
  334. {
  335. "name": "kea-dhcp6",
  336. "output_options": [
  337. {
  338. "output": "/var/log/kea-debug.log",
  339. "maxver": 8,
  340. "maxsize": 204800,
  341. "destination": "file"
  342. }
  343. ],
  344. "severity": "DEBUG",
  345. "debuglevel": 99
  346. }
  347. ]
  348. }</userinput></screen>
  349. </section>
  350. </section>
  351. <section id="logging-message-format">
  352. <title>Logging Message Format</title>
  353. <para>
  354. Each message written to the configured logging
  355. destinations comprises a number of components that identify
  356. the origin of the message and, if the message indicates
  357. a problem, information about the problem that may be
  358. useful in fixing it.
  359. </para>
  360. <para>
  361. Consider the message below logged to a file:
  362. <screen>2014-04-11 12:58:01.005 INFO [kea-dhcp4.dhcpsrv/27456]
  363. DHCPSRV_MEMFILE_DB opening memory file lease database: type=memfile universe=4</screen>
  364. </para>
  365. <para>
  366. Note: the layout of messages written to the system logging
  367. file (syslog) may be slightly different. This message has
  368. been split across two lines here for display reasons; in the
  369. logging file, it will appear on one line.
  370. </para>
  371. <para>
  372. The log message comprises a number of components:
  373. <variablelist>
  374. <varlistentry>
  375. <term>2014-04-11 12:58:01.005</term>
  376. <!-- TODO: timestamp repeated even if using syslog? -->
  377. <listitem><para>
  378. The date and time at which the message was generated.
  379. </para></listitem>
  380. </varlistentry>
  381. <varlistentry>
  382. <term>INFO</term>
  383. <listitem><para>
  384. The severity of the message.
  385. </para></listitem>
  386. </varlistentry>
  387. <varlistentry>
  388. <term>[kea-dhcp4.dhcpsrv/27456]</term>
  389. <listitem><para>
  390. The source of the message. This comprises two components:
  391. the Kea process generating the message (in this
  392. case, <command>kea-dhcp4</command>) and the module
  393. within the program from which the message originated
  394. (which is the name of the common library used by DHCP server
  395. implementations). The number after the slash is a process id
  396. (pid).
  397. </para></listitem>
  398. </varlistentry>
  399. <varlistentry>
  400. <term>DHCPSRV_MEMFILE_DB</term>
  401. <listitem><para>
  402. The message identification. Every message in Kea
  403. has a unique identification, which can be used as an
  404. index into the <ulink
  405. url="kea-messages.html"><citetitle>Kea Messages
  406. Manual</citetitle></ulink> (<ulink
  407. url="http://kea.isc.org/docs/kea-messages.html"
  408. />) from which more information can be obtained.
  409. </para></listitem>
  410. </varlistentry>
  411. <varlistentry>
  412. <term>opening memory file lease database: type=memfile universe=4</term>
  413. <listitem><para>
  414. A brief description.
  415. Within this text, information relating to the condition
  416. that caused the message to be logged will be included.
  417. In this example, the information is logged that the in-memory
  418. lease database backend will be used to store DHCP leases.
  419. </para></listitem>
  420. </varlistentry>
  421. </variablelist>
  422. </para>
  423. </section>
  424. </chapter>