Changes between Version 5 and Version 6 of LoggingCppApiDesign


Ignore:
Timestamp:
Jul 4, 2011, 10:33:28 AM (6 years ago)
Author:
stephen
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • LoggingCppApiDesign

    v5 v6  
    1414The envisaged logging hierarchy for BIND-10 involves two levels, program and component: each logging component (logger) is a child of the program's logger, which corresponds to the underlying package's root logger.  This means that setting options for the program logger applies to all logging in the program unless overridden by options set for a component-level logger; e.g. log the program at "INFO" except for the DNS library, where logging should be set to "DEBUG".  In logging output, the source of messages is identified by a combination of the program and component logger, e.g. b10-auth.dnslib.  As each program has its own set of logging options, a consequence of this is that the logging parameters for a component may be different in different programs.
    1515
    16  In most cases, each module from which a message originated (e.g. the DNS library) will have its own logger.  In other cases, the same logger could be used in different modules; for example, messages output in the process of tracing a query through the system could logged using a special "query trace" logger.
    17 
    18 == Logging Initialization ==
    19 Loggers will need to be able to access configuration information in order to set up filters and outputs. This will be stored in the configuration database and accessed in the same was as all other configuration information.  Until the configuration information has been processed, all loggers will output to stderr (or syslog?).  This can be changed using a command-line option, e.g. when the server is being run from the command line, the user will probably want log messages to be sent to stderr.
     16In most cases, each module from which a message originated (e.g. the DNS library) will have its own logger.  In other cases, the same logger could be used in different modules; for example, messages output in the process of tracing a query through the system could logged using a special "query trace" logger.
    2017
    2118== Logging ==
     
    152149 * stderr (the default for a "console" destination if no stream is specified).
    153150
     151= Logging Initialization =
     152In 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 exception.
     153call.
     154
     155== C++ ==
     156Logging 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.
     157
     158=== Initialization for Production Programs ===
     159The signature for this is:
     160{{{
     161void isc::log::initLogger(const std::string& root,
     162                          isc::log::Severity severity = isc::log::INFO,
     163                          int dbglevel = 0, const char* file = NULL);
     164}}}
     165
     166''root'': Name of the program (e.g. "b10-auth").  This is also the name of the root logger and is used when configuring logging.
     167
     168''severity'': Default severity that the program will start logging with.  Although this may be overridden when the program obtains its configuration from the configuration
     169database, this is the severity that it used until then.  (This may be set by a command-line parameter.)
     170
     171''dbglevel'': The debug level used if "severity" is set to {{{isc::log::DEBUG}}}.
     172
     173''file'': The name of a local message file.  This will be read and its definitions used to replace the compiled-in text of the messages.
     174
     175
     176=== Initialization for Unit Tests ===
     177The signature for this is:
     178{{{
     179void isc::log::initLogger()
     180}}}
     181This is the call that should be used by unit tests.  In this variant, as the unit tests will not access the configuration database, all the logging options are supplied by environment variables. (This variant should not be used for production programs to avoid the program operation being affected by inadvertently-defined environment variables.)
     182
     183The environment variables are:
     184
     185'''B10_LOGGER_ROOT''': Sets the "root" for the unit test.  If not defined, the name "bind10" is used.
     186
     187'''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, "DEBUG" is used.
     188
     189'''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 99.
     190
     191'''B10_LOGGER_LOCALMSG''': If defined, points to a local message file.  The default is not to use a local message file.
     192
     193'''B10_LOGGER_DESTINATION''': The location to which log message are written.  This can be one of:
     194
     195|| stdout || Message are written to stdout ||
     196|| stderr || Messages are written to stderr ||
     197|| 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.) ||
     198|| 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. ||
     199
     200In the case of "stdout", "stderr" and "syslog", they must be written exactly as is - no leading or trailing spaces, and in lower-case.
     201
     202Note that the default is DEBUG severity at maximum detail. This can lead to the tests generating lot of messages, which can be suppressed if B10_LOGGER_DESTINATION is set to /dev/null.  This method of suppression is preferred to setting B10_LOGGER_SEVERITY to NONE as it exercises all the code.  As indicated above, the expansion of the LOG_DEBUG macro results in code similar to:
     203{{{
     204if (logger.isDebugEnabled()) {
     205logger.debug(code, level).arg(expensive_call_to_format_data());
     206}
     207}}}
     208Testing all code paths, including the call to {{{expensive_call_to_format_data()}}}, requires running unit tests such that they log everything with maximum detail.  In this case, routing output to /dev/null will suppress the messages.
     209
     210== Python ==
     211To be supplied
     212
     213
     214
    154215= Implementation Notes =
    155216 * The idea of messages in external files is described in more detail [wiki:ExternalMessageFiles here].