[master] Merge branch 'trac3805'

doc/guide/logging.xml

@@ -45,18 +45,37 @@
         <title>Loggers</title>
 
         <para>
-          Within Kea, a message is logged through an entity
-          called a "logger". Different parts of the code log messages
-          through different loggers, and each logger can be configured
-          independently of one another. For example there are different
-          components that deal with hooks ("hooks" logger) and with
-          DHCP engine ("dhcpsrv" logger).
+          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 is using 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
+          or libhooks library, use their own loggers.
         </para>
 
         <para>
-          In the Logging structure in a configuration file you can
-          specify the configuration for zero or more loggers. If there are
-          no loggers specified, the code will use default values which
+          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
+          messages emitted from the hooks library can be distingued from
+          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.
+        </para>
+
+        <para>
+          In the <quote>Logging</quote> structure 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 which
           cause Kea to log messages on at least INFO severity to standard
           output.
           <!-- @todo: add reference to section about controlling default
@@ -85,7 +104,7 @@
           </para>
 
           <para>
-            When diagnosing the problem with the server's operation it is often
+            When diagnosing the problem with the server's operation, it is often
             desired to use the DEBUG logging level to obtain the verbose output
             from the server and libraries it uses. However, high verbosity may
             be an overkill for the logging system in cases when the server
@@ -323,6 +342,28 @@
 
         </itemizedlist>
 
+        <para>
+          Note that user-defined hook libraries should not use any of those
+          loggers, and should define new loggers with names that correspond to
+          the libraries using them. Suppose that the user created the library called
+          <quote>libpacket-capture</quote> to dump packets received and
+          transmitted by the server to the file. The appropriate name for the
+          logger could be <command>kea-dhcp4.packet-capture</command>. Note
+          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,
+          unless there is a separate configuration entry for the child logger
+          which overrides the default configuration.
+        </para>
+
+        <para>
+          The list of loggers above excludes any loggers implemented in hooks
+          libraries. Please consult the documentation of the specific hooks
+          libraries for the names of loggers they define.
+        </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

src/lib/hooks/hooks_user.dox

@@ -1,4 +1,4 @@
-// Copyright (C) 2013-2014  Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2013-2015  Internet Systems Consortium, Inc. ("ISC")
 //
 // Permission to use, copy, modify, and/or distribute this software for any
 // purpose with or without fee is hereby granted, provided that the above
@@ -109,7 +109,7 @@ the hardware address and allocated IP address for the clients of interest.
 The following sections describe how to implement these requirements.
 The code presented here is not efficient and there are better ways of
 doing the task.  The aim however, is to illustrate the main features of
-user hook code not to provide an optimal solution.
+user hooks code, not to provide an optimal solution.
 
 
 @subsection hooksdgFrameworkFunctions Framework Functions
@@ -576,6 +576,118 @@ int pkt4_send(CalloutHandle& handle) {
 }
 @endcode
 
+@subsection hooksdgLogging Logging in the Hooks Library
+
+Hooks libraries take part in the DHCP message processing. They also often
+modify the server's behavior by taking responsibility for processing
+the DHCP message at certain stages and instructing the server to skip
+the default processing for that stage. Thus, hooks libraries play an
+important role in the DHCP server operation and, depending on their
+purpose, they may have high complexity, which increases likehood of the
+defects in the libraries.
+
+All hooks libraries should use Kea logging system to faciliate diagnostics
+of the defects in the libraries and issues with the DHCP server's operation.
+Even if the issue doesn't originate in the hooks library itself, the use
+of the library may uncover issues in the Kea code that only
+manifest themselves in some special circumstances.
+
+Hooks libraries use the Kea logging system in the same way as any other
+standard Kea library. A hooks library should have at least one logger
+defined, but may have multiple loggers if it is desired
+to separate log messages from different functional parts of the library.
+
+Assuming that it has been decided to use logging in the hooks library, the
+implementor must select a unique name for the logger. Ideally the name
+should have some relationship with the name of the library so that it is
+easy to distinguish messages logged from this library. For example,
+if the hooks library is used to capture incoming and outgoing DHCP
+messages, and the name of the library is "libkea-packet-capture",
+a suitable logger name could be "packet-capture".
+
+In order to use a logger within the library, the logger should be declared
+in a header file, which must be included in all files using
+the logger:
+
+@code
+#ifndef PACKET_CAPTURE_LOG_H
+#define PACKET_CAPTURE_LOG_H
+
+#include <log/message_initializer.h>
+#include <log/macros.h>
+#include <user_chk_messages.h>
+
+namespace packet_capture {
+
+extern isc::log::Logger packet_capture_logger;
+
+}
+
+#endif
+@endcode
+
+The logger should be defined and initialized in the implementation file,
+as illustrated below:
+
+@code
+#include <packet_capture_log.h>
+
+namespace packet_capture {
+
+isc::log::Logger packet_capture_logger("packet-capture");
+
+}
+@endcode
+
+These files may contain multiple logger declarations and initializations
+when the use of more than one logger is desired.
+
+The next step is to add the appropriate message file as described in the
+@ref logMessageFiles.
+
+The implementor must make sure that log messages appear in the right
+places and that they are logged at the appropriate level. The choice
+of the place where the message should appear is not always obvious:
+it depends if the particular function being called already logs enough
+information and whether adding log message before and/or after the
+call to this function would simply duplicate some messages. Sometimes
+the choice whether the log message should appear within the function or
+outside of it depends on the level of details available for logging. For
+example, in many cases it is desirable to include the client identifier
+or transaction id of the DHCP packet being processed in logging message.
+If this information is available at the higher level but not in the
+function being called, it is often better to place the log message at
+higher level.  However, the function parameters list could be extended
+to include the additional information, and to be logged and the logging
+call made from within the function.
+
+Ideally, the hooks library should contain debug log messages (traces)
+in all significant decision points in the code, with the information as to
+how the code hit this decision point, how it will proceed and why.
+However, care should be taken when selecting the log level for those
+messages, because selecting too high logging level may impact the
+performance of the system. For this reason, traces (messages of
+the debug severity) should use different debug levels for the
+messages of different importance or having different performance
+requirements to generate the log message. For example, generation of
+a log message, which prints full details of a packet, usually requires
+more CPU bandwith than the generation of the message which only prints
+the packet type and length. Thus, the former should be logged at
+lower debug level (see @ref logSeverity for details of using
+various debug levels using "dbglevel" parameter).
+
+All loggers defined within the hooks libraries derive the default
+configuration from the root logger. For example, when the hooks
+library is attached to the DHCPv4 server, the root logger name is
+"kea-dhcp4", and the library by default uses configuration of this
+logger. The configuration of the library's logger can
+be modified by adding a configuration entry for it
+to the configuration file. In case of the "packet-capture"
+logger declared above, the full name of the logger in the
+configuration file will be "kea-dhcp4.packet-capture". The
+configuration specified for this logger will override the default
+configuration derived from the root logger.
+
 @subsection hooksdgBuild Building the Library
 
 Building the code requires building a sharable library.  This requires