wiki:LoggingRequirements

Introduction

These requirements are based on the BIND 9 Logging features and those for Python. They have also been influenced by the capabilities of external logging packages (such as Apache log4cxx and Pantheios) and input from discussions on the bind10-dev mailing list and elsewhere.

The requirements apply to both C++ and Python logging.

Logging Sources

  • Each message should be associated with up to two sources:
    • One source should be the name of the component (e.g. "DNS library")
    • One source should be the program in which the component is running (e.g. "recursive server")
    • The sources should be hierarchical: a change affecting the program source applies to all contained components unless overridden at the component level.

(Note that this means that a component can appear under several guises, e.g. the DNS library is a component in its own right, but may appear in both the authoritative server an recursive server.)

  • It should be possible to enable or disable logging messages by source; by default all sources should be enabled.
  • It should be possible to enable or disable the logging from a query source via configuration options.

Logging Severities

  • Each logging message must be assigned a severity. Although the severity categories are arbitrary, there must be a correspondence to the following:
    • CRITICAL: also known as FATAL severity, the message is associated with a condition that means that the program cannot continue. An example of this would be the authoritative server starting but being unable to connect to the command channel. It is expected that the program will shortly terminate after this message is output.
    • ERROR: a condition has occurred which means that future operation may not give the expected results; however the program can continue. For example, an authoritative server configured to server two zones is not able to get the information for one of them; it can serve the data for the other zone, but not for the zone where there is a problem.
    • WARNING: a condition has occurred that should not have happened. However the server is able to recover and continue operation. For example, at the command level attempting to delete a non-existent configuration parameter.
    • INFORMATION: an event of note has occurred, e.g. the server has started.
    • DEBUG: a message only of use to developers.
  • It must be possible to set a filter on a source such that only messages of a given severity and above are output (where DEBUG < INFO < WARNING < ERROR < CRITICAL).
  • It should be possible to set a filter on a program/component combination (e.g. the DNS library only outputs critical messages except when running in the authoritative server where it output debug messages.)
  • Setting of the severity filter should be possible be via a configuration option.

Debug Levels

  • Each debug message must have a level (a number between 1 and 100) assigned to it; the higher the number the more detailed the information output.
  • It must be possible to set a filter for debug messages such that only messages of a given level or below are output.
  • It should be possible to set the debugging level via the command interface.

Logging Output

  • It must be possible to route output to different destinations based on source and severity.
  • Destinations should include
    • stderr
    • syslog
    • user-specified file
      • It should be possible to specify a maximum size for the file after which the logging stops or the file is rotated. (The operation should happen before the set file size is exceeded, not after.)
      • If the rotation option is specified, it should be possible to specify the number of versions of a file retained.
      • It should be possible to request a file rotation at any time.
      • It should be possible to schedule regular file rotations.
      • It should be possible to set a pattern for the name of rotated files (e.g. /var/log/bind10/bind10-%Y%m%d.log)
    • named socket
  • For each destination, it should be possible to set up a secondary output destination:
    • If a write to the primary destination fails, output should be sent to the secondary destination.
    • Where the primary destination is a user-specified file, the following should apply:
      • Is the failure is due to a disk full error, the system must attempt to repeat the output of the message for a configurable number of times with a configurable delay between (default: one repeat after a pause of one second) before routing to the secondary destination.
      • Messages arriving in the meantime should be buffered; if any are lost because of buffer overflow, a note should be made and a message generated and written to the log when it is possible to do so.
    • It should be configurable as to whether in the case of an error output is:
      • Permanently re-routed to the secondary destination.
      • Re-routed for a specified period of time before the primary is re-tried
  • It should be possible to send a message to more than one destination.
  • A single destination should be able to receive messages from more than one source.
  • It should be possible to set logging destinations via the command interface.
  • During program start-up, messages should be routed to stderr until the logging is initialized.
  • It should be possible to specify the format of a message (e.g. whether the message is time-stamped) on a per-destination basis.

Performance

  • The overhead of a logging statement should be minimal if the selection criteria are such that the associated message is not output.

Miscellaneous

  • Every log message should have a unique identification which should be included in the message output
  • It should be possible to (easily) change the language of messages

Notes

Debug Levels

To be supplied: guidance on use of debug levels

Last modified 7 years ago Last modified on Dec 12, 2010, 10:05:50 AM