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
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.
==========================
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:
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
===================
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
=====
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.
// 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;
} 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);
// Initialize logging
initLogger(root, severity, dbglevel, localfile);
- // Now set the destination
+ // Now set the destination for logging output
setDestination(root, severity, dbglevel);
}
projects / thirdparty / kea.git / commitdiff
