From: Stephen Morris Date: Thu, 30 Jun 2011 09:20:09 +0000 (+0100) Subject: [trac1071] Update documentation and final tidy-up X-Git-Tag: perftcpdns_before_epoll~231^2~22^2~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4355e75c9f82ea797d9353e82fd4d7c445c9e5c2;p=thirdparty%2Fkea.git [trac1071] Update documentation and final tidy-up --- diff --git a/src/lib/log/README b/src/lib/log/README index e09691ad78..298004da9d 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 eac2fbbe8b..2c5ab455e2 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 3cf52024fc..104c0780f3 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**) {