Commit 51c4d4d1 authored by Stephen Morris's avatar Stephen Morris
Browse files

[3805] Miscellaneous edits to the documentation update

parent 209fe7fc
......@@ -48,10 +48,10 @@
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 DHCP server
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 different logger for messages
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
......@@ -59,14 +59,16 @@
</para>
<para>
Users implementing hooks libraries, attached to the server at
runtime, are responsible for creating loggers exclusively used
by those libraries. Such loggers are configured independently
from other loggers and should have unique names to allow for
distingushing messages emitted from the hook library from
messages emitted by the core Kea code. Whenever it makes sense,
hook library can use multiple loggers to log messages pertaining
to different logical parts of the library.
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>
......@@ -341,7 +343,7 @@
</itemizedlist>
<para>
Note that user defined hook libraries should not use any of those
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
......@@ -359,7 +361,7 @@
<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!
libraries for the names of loggers they define.
</para>
<para>Additional loggers may be defined in the future. The easiest
......
// 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
......@@ -581,32 +581,32 @@ int pkt4_send(CalloutHandle& handle) {
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
this processing stage. Thus, hooks libraries play an important role in the
DHCP server operation and, depeneding on their purpose, they may
have high complexity, which increases likehood of the defects in the
libraries.
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 must use Kea logging system to faciliate diagnostics
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 origin in the hooks library itself, the use
of the library may uncover issues in the Kea code, which only
manifest in some special circumstances.
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. Hooks library must have at least one logger
defined, but it may also have multiple loggers if it is desired
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.
Hooks library implementor must select the unique name for the logger,
and this name should correspond with the name of the library, so as it is
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",
the suitable logger name could be "packet-capture", or other name that
can be easily associated with the library and its purpose.
a suitable logger name could be "packet-capture".
In order to create a logger within the library, it should be declared
in the new header file, which must be included in all files using
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
......@@ -626,8 +626,8 @@ extern isc::log::Logger packet_capture_logger;
#endif
@endcode
Then the logger should be initialized in the implementation file
like this:
The logger should be defined and initialized in the implementation file,
as illustrated below:
@code
#include <packet_capture_log.h>
......@@ -645,29 +645,28 @@ 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.
Implementor must make sure that log messages appear in the right places
and that they are logged at the appropriate level. 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
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 in the function and outside of it. For
example, in most cases it is desired to log the client identifier or
transaction id of the DHCP packet being processed, and for which the
particular message is logged. If this information is available at the
higher level, but not available in the function being called, it is
often better to place the log message at higher level, where client
identifier and/or transaction id is present and can be included in
the logged message. Alternatively, the function parameters list can
be extended to include additional information to be logged.
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
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. This also means that traces (messages of
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
......@@ -681,9 +680,9 @@ 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 logger used within the library can
be modified by putting the configuration entry for the library
logger in the configuration file. In case of the "packet-capture"
logger. The configuration of the library's logger can
be modified by putting 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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment