BIND 10 trac1071, updated. 4355e75c9f82ea797d9353e82fd4d7c445c9e5c2 [trac1071] Update documentation and final tidy-up
BIND 10 source code commits
bind10-changes at lists.isc.org
Thu Jun 30 09:20:42 UTC 2011
The branch, trac1071 has been updated
via 4355e75c9f82ea797d9353e82fd4d7c445c9e5c2 (commit)
from 4b83a53a37e3fa53a01ca0a6b4c9f7846a64bc5e (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 4355e75c9f82ea797d9353e82fd4d7c445c9e5c2
Author: Stephen Morris <stephen at isc.org>
Date: Thu Jun 30 10:20:09 2011 +0100
[trac1071] Update documentation and final tidy-up
-----------------------------------------------------------------------
Summary of changes:
src/lib/log/README | 181 +++++++++++++++++----------------
src/lib/log/logger_support.cc | 41 +++++---
src/lib/log/tests/init_logger_test.cc | 7 +-
3 files changed, 124 insertions(+), 105 deletions(-)
-----------------------------------------------------------------------
diff --git a/src/lib/log/README b/src/lib/log/README
index e09691a..298004d 100644
--- a/src/lib/log/README
+++ b/src/lib/log/README
@@ -142,6 +142,12 @@ Points to note:
the error originated from the logging library and the "WRITE_ERROR"
indicates that there was a problem in a write operation.
+ * The rest of the line - from the first non-space character to the last non-
+ space character - is taken exactly as-is for the text of the message. There
+ are no restrictions on what characters may be in this text, other than they
+ be printable. (This means that both single-quote (') and double-quote (")
+ characters are allowed.)
+
* 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
@@ -233,7 +239,7 @@ Using the Logging - C++
1. Build message header file and source file as describe above.
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
+ (described in more detail below) to set the logging severity, debug log
level, and external message file:
a) The logging severity is one of the enum defined in logger.h, i.e.
@@ -279,9 +285,9 @@ Using the Logging - Python
==========================
1. Build message module as describe above.
-2. The main program unit should include a call to isc.log.init() to
- set the to set the logging severity, debug log level, and external
- message file:
+2. The main program unit should include a call to isc.log.init()
+ (described in more detail below) to set the to set the logging
+ severity, debug log level, and external message file:
a) The logging severity is one of the strings:
@@ -316,6 +322,91 @@ Using the Logging - Python
logger.error(LOG_WRITE_ERROR, "output.txt");
+Logging Initialization
+======================
+In all cases, if an attempt is made to use a logging method before the logging
+has been initialized, the program will terminate with a LoggingNotInitialized
+call.
+
+C++
+---
+Logging Initialization is carried out by calling initLogger(). There are two
+variants to the call, one for use by production programs and one for use by
+unit tests.
+
+Variant #1, Used by Production Programs
+---------------------------------------
+ void initLogger(const std::string& root,
+ isc::log::Severity severity = isc::log::INFO,
+ int dbglevel = 0, const char* file = NULL);
+
+This is the call that should be used by production programs:
+
+root
+Name of the program (e.g. "b10-auth"). This is also the name of the root
+logger and is used when configuring logging.
+
+severity
+Default severity that the program will start logging with. Although this may
+be overridden when the program obtains its configuration from the configuration
+database, this is the severity that it used until then. (This may be set by
+a command-line parameter.)
+
+dbglevel
+The debug level used if "severity" is set to isc::log::DEBUG.
+
+file
+The name of a local message file. This will be read and its defintitions used
+to replace the compiled-in text of the messages.
+
+
+Variant #2, Used by Unit Tests
+------------------------------
+ void initLogger()
+
+This is the call that should be used by unit tests. In this variant, all the
+options are supplied by environment variables. (It should not be used for
+production programs to avoid the chance that the program operation is affected
+by inadvertantly-defined environment variables.)
+
+The environment variables are:
+
+B10_LOGGER_ROOT
+Sets the "root" for the unit test. If not defined, the name "bind10" is used.
+
+B10_LOGGER_SEVERITY
+The severity to set for the root logger in the unit test. Valid values are
+"DEBUG", "INFO", "WARN", "ERROR", "FATAL" and "NONE". If not defined, "INFO"
+is used.
+
+B10_LOGGER_DBGLEVEL
+If B10_LOGGER_SEVERITY is set to "DEBUG", the debug level. This can be a
+number between 0 and 99, and defaults to 0.
+
+B10_LOGGER_LOCALMSG
+If defined, points to a local message file. The default is not to use a local
+message file.
+
+B10_LOGGER_DESTINATION
+The location to which log message are written. This can be one of:
+
+ stdout Message are written to stdout
+ stderr Messages are written to stderr
+ syslog[:facility] Messages are written to syslog. If the optional
+ "facility" is used, the messages are written using
+ that facility. (This defaults to "local0" if not
+ specified.)
+ Anything else Interpreted as the name of a file to which output
+ is appended. If the file does not exist, a new one
+ is opened.
+
+In the case of "stdout", "stderr" and "syslog", they must be written exactly
+as is - no leading or trailing spaces, and in lower-case.
+
+Python
+------
+To be supplied
+
Severity Guidelines
===================
@@ -410,44 +501,6 @@ logger "pkt-auth".) As the loggers are independent and the severity
levels independent, fine-tuning of what and what is not recorded can
be achieved.
-Logging Initialization
-======================
-In all cases, if an attempt is made to use a logging method before the logging
-has been initialized, the program will terminate with a LoggingNotInitialized
-call.
-
-C++
----
-Logging Initialization is carried out by calling initLogger(). There are two
-variants to the call, one for use by production programs and one for use by
-unit tests.
-
-Variant #1, Used by Production Programs
----------------------------------------
- void initLogger(const std::string& root,
- isc::log::Severity severity = isc::log::INFO,
- int dbglevel = 0, const char* file = NULL);
-
-This is the call that should be used by production programs:
-
-root
-Name of the program (e.g. "b10-auth"). This is also the name of the root
-logger and is used when configuring logging.
-
-severity
-Default severity that the program will start logging with. Although this may
-be overridden when the program obtains its configuration from the configuration
-database, this is the severity that it used until then. (This may be set by
-a command-line parameter.)
-
-dbglevel
-The debug level used if "severity" is set to isc::log::DEBUG.
-
-file
-The name of a local message file. This will be read and its defintitions used
-to replace the compiled-in text of the messages.
-
-
Notes
=====
@@ -457,47 +510,3 @@ in both the message compiler and the server; in the server it is used
when the server starts up (or when triggered by a command) to read in
a message file to overwrite the internal dictionary. Writing it in C++
means there is only one piece of code that does this functionality.
-
-
-Variant #2, Used by Unit Tests
-------------------------------
- void initLogger()
-
-This is the call that should be used by unit tests. In this variant, all the
-options are supplied by environment variables. (It should not be used for
-production programs to avoid the chance that the program operation is affected
-by inadvertantly-defined environment variables.)
-
-The environment variables are:
-
-B10_LOGGER_ROOT
-Sets the "root" for the unit test. If not defined, the name "bind10" is used.
-
-B10_LOGGER_SEVERITY
-The severity to set for the root logger in the unit test. Valid values are
-"DEBUG", "INFO", "WARN", "ERROR", "FATAL" and "NONE". If not defined, "INFO"
-is used.
-
-B10_LOGGER_DBGLEVEL
-If B10_LOGGER_SEVERITY is set to "DEBUG", the debug level. This can be a
-number between 0 and 99, and defaults to 0.
-
-B10_LOGGER_LOCALMSG
-If defined, points to a local message file. The default is not to use a local
-message file.
-
-B10_LOGGER_DESTINATION
-The location to which log message are written. This can be one of:
-
- stdout Message are written to stdout
- stderr Messages are written to stderr
- syslog[:facility] Messages are written to syslog. If the optional
- "facility" is used, the messages are written using
- that facility. (This defaults to "local0" if not
- specified.)
- Anything else Interpreted as the name of a file to which output
- is appended. If the file does not exist, a new one
- is opened.
-
-In the case of "stdout", "stderr" and "syslog", they must be written exactly
-as is - no leading or trailing spaces, and in lower-case.
diff --git a/src/lib/log/logger_support.cc b/src/lib/log/logger_support.cc
index eac2fbb..2c5ab45 100644
--- a/src/lib/log/logger_support.cc
+++ b/src/lib/log/logger_support.cc
@@ -44,27 +44,34 @@ bool logging_init_state = false;
// Set logging destination according to the setting of B10_LOGGER_DESTINATION.
-// (See header for initLogger() for more details.)
+// (See header for initLogger() for more details.) This is a no-op if the
+// environment variable is not defined.
+//
+// \param root Name of the root logger
+// \param severity Severity level to be assigned to the root logger
+// \param dbglevel Debug level
+
void
setDestination(const char* root, const isc::log::Severity severity,
const int dbglevel) {
using namespace isc::log;
- // Constants:
- static const string STDOUT = "stdout";
- static const string STDERR = "stderr";
- static const string SYSLOG = "syslog";
- static const string SYSLOG_COLON = "syslog:";
-
-
const char* destination = getenv("B10_LOGGER_DESTINATION");
if (destination != NULL) {
- // Destination is present, adjust root logger destination to it.
+ // Constants: not declared static as this is function is expected to be
+ // called once only
+ const string STDOUT = "stdout";
+ const string STDERR = "stderr";
+ const string SYSLOG = "syslog";
+ const string SYSLOG_COLON = "syslog:";
+
+ // Prepare the objects to define the logging specification
LoggerSpecification spec(root, severity, dbglevel);
OutputOption option;
+ // Set up output option according to destination specification
const string dest = destination;
if (dest == STDOUT) {
option.destination = OutputOption::DEST_CONSOLE;
@@ -76,28 +83,30 @@ setDestination(const char* root, const isc::log::Severity severity,
} else if (dest == SYSLOG) {
option.destination = OutputOption::DEST_SYSLOG;
- option.facility = "local0";
+ // Use default specified in OutputOption constructor for the
+ // syslog destination
} else if (dest.find(SYSLOG_COLON) == 0) {
option.destination = OutputOption::DEST_SYSLOG;
- // Must take account of the string actually being "syslog:".
+ // Must take account of the string actually being "syslog:"
if (dest == SYSLOG_COLON) {
cerr << "**ERROR** value for B10_LOGGER_DESTINATION of " <<
SYSLOG_COLON << " is invalid, " << SYSLOG <<
" will be used instead\n";
- option.facility = "local0";
+ // Use default for logging facility
+
} else {
- // Everything else is the facility name
+ // Everything else in the string is the facility name
option.facility = dest.substr(SYSLOG_COLON.size());
}
} else {
- // Not a recognised destination, assume a file.
+ // Not a recognised destination, assume a file
option.destination = OutputOption::DEST_FILE;
option.filename = dest;
}
- // ... and set it.
+ // ... and set the destination
spec.addOutputOption(option);
LoggerManager manager;
manager.process(spec);
@@ -185,7 +194,7 @@ void initLogger(isc::log::Severity severity, int dbglevel) {
// Initialize logging
initLogger(root, severity, dbglevel, localfile);
- // Now set the destination
+ // Now set the destination for logging output
setDestination(root, severity, dbglevel);
}
diff --git a/src/lib/log/tests/init_logger_test.cc b/src/lib/log/tests/init_logger_test.cc
index 3cf5202..104c078 100644
--- a/src/lib/log/tests/init_logger_test.cc
+++ b/src/lib/log/tests/init_logger_test.cc
@@ -20,9 +20,10 @@ using namespace isc::log;
/// \brief Test InitLogger
///
-/// A test program that initializes using initLogger(), then outputs several
-/// messages at different severities. An external script sets the environment
-/// variables and checks that they have the desired effect.
+/// A program used in testing the logger that initializes logging using
+/// initLogger(), then outputs several messages at different severities and
+/// debug levels. An external script sets the environment variables and checks
+/// that they have the desired effect.
int
main(int, char**) {
More information about the bind10-changes
mailing list