BIND 10 trac899, updated. 0dcde0e52b99cade8f584751b2d2756c20e78625 [trac899] Updated README file
BIND 10 source code commits
bind10-changes at lists.isc.org
Fri May 20 12:49:29 UTC 2011
The branch, trac899 has been updated
via 0dcde0e52b99cade8f584751b2d2756c20e78625 (commit)
from f1213a3d4df71a4009a3f9a09a9aab002b42ce35 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 0dcde0e52b99cade8f584751b2d2756c20e78625
Author: Stephen Morris <stephen at isc.org>
Date: Fri May 20 13:49:16 2011 +0100
[trac899] Updated README file
-----------------------------------------------------------------------
Summary of changes:
src/lib/log/README | 99 ++++++++++++++--------------------------------------
1 files changed, 26 insertions(+), 73 deletions(-)
-----------------------------------------------------------------------
diff --git a/src/lib/log/README b/src/lib/log/README
index 529eefc..6b4cf11 100644
--- a/src/lib/log/README
+++ b/src/lib/log/README
@@ -117,7 +117,7 @@ Points to note:
* Lines starting $ are directives. At present, two directives are recognised:
* $PREFIX, which has one optional argument: the string used to prefix symbols.
- If absent, there is no prefix to the symbols. (Prefixes are explained below.)
+ If absent, there is no prefix to the symbols (prefixes are explained below).
* $NAMESPACE, which has one argument: the namespace in which the symbols are
created. In the absence of a $NAMESPACE directive, symbols will be put in
@@ -135,7 +135,7 @@ Points to note:
* The replacement tokens are the strings "%1", "%2" etc. When a message
is logged, these are replaced with the arguments passed to the logging
call: %1 refers to the first argument, %2 to the second etc. Within the
- message text, the placeholders can appear in any order, and placeholders
+ message text, the placeholders can appear in any order and placeholders
can be repeated.
* Remaining lines indicate an explanation for the preceding message. These
@@ -215,33 +215,9 @@ To use the current version of the logging:
1. Build message header file and source file as describe above.
-2. In the main module of the program, declare an instance of the
- RootLoggerName class to define the name of the program's root logger, e.g.
-
- #include <log/root_logger_name.h>
-
- isc::log::RootLoggerName("b10-auth");
-
- This can be declared inside or outside an execution unit.
-
-2. In the code that needs to do logging, declare a logger with a given name,
- e.g.
-
- #include <log/logger.h>
- :
- isc::log::Logger logger("myname"); // "myname" can be anything
-
- The above example assumes declaration outside a function. If declaring
- non-statically within a function, declare it as:
-
- isc::log::Logger logger("myname", true);
-
- (The argument is required to support a possible future implementation of
- logging. Currently it has no effect.)
-
-3. The main program unit should include a call to isc::log::initLogger()
+2. The main program unit should include a call to isc::log::initLogger()
(defined in logger_support.h) to set the logging severity, debug log level,
- and external message file.
+ and external message file:
a) The logging severity is one of the enum defined in logger.h, i.e.
@@ -262,56 +238,43 @@ To use the current version of the logging:
directive of a particular type will be ignored; multiple directives will
cause the read of the file to fail with an error.)
-4. Issue logging calls using methods on logger, e.g.
+ The settings remain in effect until the logging configuration is read, and
+ so provide the default logging during program initialization.
- logger.error(DPS_NSTIMEOUT).arg("isc.org");
+3. Issue logging calls using supplied macros in "log/macros.h", e.g.
- (where, in the example above we might have defined the symbol in the message
+ LOG_ERROR(logger, DPS_NSTIMEOUT).arg("isc.org");
+
+ (The macros are more efficient that calls to the methods on the logger class:
+ they avoid the overhead of evaluating the parameters to arg() if the
+ settings are such that the message is not going to be output.)
+
+ Note: in the example above we might have defined the symbol in the message
file with something along the lines of:
$PREFIX DPS_
:
NSTIMEOUT queries to all nameservers for %1 have timed out
- At present, the only logging is to the console.
-
-
-Efficiency Considerations
--------------------------
-A common pattern in logging is a debug call of the form:
-
- logger.debug(dbglevel, MSGID).arg(expensive_call()).arg(...
-
-... where "expensive_call()" is a function call to obtain logging information
-that may be computationally intensive. Although the cost may be justified
-when debugging is enabled, the cost is still incurred even if debugging is
-disabled and the debug() method returns without outputting anything. (The
-same may be true of other logging levels, although there are likely to be
-fewer calls to logger.info(), logger.error() etc. throughout the code and
-they are less likely to be disabled.)
-
-For this reason, a set of macros is provided and are called using the
-construct:
-
- LOG_DEBUG(logger, dbglevel, MSGID).arg(expensive_call()).arg(...
- LOG_INFO(logger, MSGID).arg(expensive_call()...)
-
-If these are used, the arguments passed to the arg() method are not evaluated
-if the relevant logging level is disabled.
-
-
Severity Guidelines
===================
When using logging, the question arises, what severity should a message be
logged at? The following is a suggestion - as always, the decision must be
made in the context of which the message is logged.
+One thing that should always be borne in mind is whether the logging could
+be used as a vector for a DOS attack. For example, if a warning message is
+logged every time an invalid packet is received, an attacker could simply send
+large numbers of invalid packets. (Of course, warnings could be disabled (or
+just warnings for that that particular logger), but nevertheless the message
+is an attack vector.)
+
FATAL
-----
-The program has encountered an error that is so severe that it cannot
-continue (or there is no point in continuing). When a fatal error has been
-logged, the program will usually exit immediately (via a call to abort()) or
-shortly afterwards, after dumping some diagnostic information.
+The program has encountered an error that is so severe that it cannot continue
+(or there is no point in continuing). When a fatal error has been logged,
+the program will usually exit immediately (or shortly afterwards) after
+dumping some diagnostic information.
ERROR
-----
@@ -342,7 +305,7 @@ are distributed between the levels is up to the developer. So if debugging
the NSAS (for example), a level 0 message might record the creation of a new
zone, a level 10 recording a timeout when trying to get a nameserver address,
but a level 50 would record every query for an address. (And we might add
-level 51 to record every update of the RTT.)
+level 70 to record every update of the RTT.)
Note that like severities, levels are cumulative; so if level 25 is set as the
debug level, all debug levels from 0 to 25 will be output. In fact, it is
@@ -397,13 +360,3 @@ is only one piece of code that does this functionality.
Outstanding Issues
==================
* Ability to configure system according to configuration database.
-
-
-log4cxx Issues
-==============
-Some experimental code to utilise log4cxx as an underlying implementation
-is present in the source code directory although it is not currently used.
-The files are:
-
- logger_impl_log4cxx.{cc,h}
- xdebuglevel.{cc,h}
More information about the bind10-changes
mailing list