wiki:UsingBind9Logging

Introduction

This brief document compares and contrasts BIND 9 logging and proposed BIND 10 logging designs, and makes a recommendation as to whether BIND 10 logging can be implemented using the BIND 9 logging library.

Logging Ideas

BIND 9 Logging

Message Information

In BIND 9, each message logged is associated with the following pieces of information:

  • Category: describes the conceptual nature of the message, i.e. what general aspect of the code it is concerned with. For example, the BIND 9 DNS library defines categories that include the workings of the database as well security issues.
  • Module: loosely speaking, the origin of a message. Though there is not a one-to-one correspondence of source files with modules, it is typical that a module's name reflect the source file in which it is defined.
  • Priority: also referred to as "level" in the BIND 9 documentation, this an indication of the message severity.

Concerning the message level, there are six standard logging levels more or less corresponding to "syslog" levels. In order, from most to least severe, these are:

  • CRITICAL: an error so severe it causes the program to exit.
  • ERROR: a very notable error, but the program can go on.
  • WARNING: something is probably not as it should be.
  • NOTICE: notable events that occur while the program runs.
  • INFO: statistics, typically.
  • DEBUG: detailed debugging messages.

DEBUG is further subdivided in that each debug message is associated with a "debug level" that defines how detailed the message is; a higher level indicates more detailed information.

Message Destinations

A message destination is described by a channel, which specifies where a message is sent to. BIND 9 allows messages to be sent to:

  • Syslog.
  • A file.
  • A previously-opened file descriptor. This allows (for example) a program to open a pipe and have the logging system write messages down that pipe.
  • Null - don't write the message.

The routine of message to message destinations is done by associating a category/module pair with a given channel. (It is possible to use one function call to say "all modules coupled with this category" and vice versa, but conceptually the matching is still referred to as applying to category/module pairs, since that is what comes in from functions writing messages.)

When a message is logged, the logging system first looks up a list that consists of all of the channels associated with a particular category. It walks down the list looking for each channel that also has the indicated module associated with it, and writes the message to each channel it encounters. If no match is found in the list for the module, the default channel is used. Similarly, the default is used if no channels have been specified for the category at all.

BIND 10 Logging

Message Information

In the proposed BIND 10 system, each message logged has three associated pieces of information:

  • The name of the logger that logged the message.
  • A severity.
  • A unique identification

The logger name is hierarchical in that a logger is associated with a parent logger, which in turn is associated with its parent, all the way up to the root logger for a program. The main aspect of the relationship is that a logger inherits its parent's attributes (e.g. severity of the message to log) unless an attribute is explicitly set.

Concerning the severity, a message is logged with one of the following severities:

  • FATAL: an error so severe it causes the program to exit.
  • ERROR: a very notable error, but the program can go on.
  • WARNING: something is probably not as it should be.
  • INFO: notable events that occur while the program runs.
  • DEBUG: detailed debugging messages.

DEBUG is further subdivided in that each debug message is associated with a "debug level" that defines how detailed the message is; a higher level indicates more detailed information.

A message identification is a tag unique across all messages in BIND 10. This has two purposes:

  • It uniquely identifes each message in the system.
  • It allows message text to be overridden at run time, e.g. by a foreign language translation.

Messages are defined in external files which are processed to produce files for inclusion into the build process. The external message files should also contain detailed information for each message, so allowing a manual to be created for support personnel. (This is another reason for the message tag - even when the message text is translated, the tag is included in the message to allow the source of the message to be identified.)

Message Destinations

The idea of the BIND 10 logging is to follow the ideas of logging systems like log4j, where one or more "appenders" can be attached to a particular logger. Messages are logged by all appenders attached to the logger and are then passed to loggers higher up the tree. So if (for example) the root logger was logging to the console and the logger "xyz" set to log to a file, then anything logged by "xyz" would log to both the file and to the console. (The behaviour can be overridden so that when a message is logged, it is not passed up the tree.)

BIND 9 and BIND 10 Logging Comparison

Message Severity

To dispose of the most obvious correspondence first, both messages have a severity level. The levels are slightly different although there is broadly a 1:1 correspondence:

BIND 9 Level BIND 10 Level
CRITICAL FATAL
ERROR ERROR
WARNING WARNING
NOTICE INFO
INFO (see below)
DEBUG DEBUG

The BIND 9 level of INFO is used mainly for statistics. In BIND 10, statistics are extracted by specialist statistics code and are not output through the logging system.

Message Source

Things are somewhat more complicated when it comes to the idea of message source. BIND 9 associated two (independent) pieces of information with each message (a category and module) whereas BIND 10 associates only one (the logger name). Also, all BIND 9 messages come from one executable whereas the BIND 10 functions are split across multiple images. However, the hierarchical nature of the BIND 10 logging allows a correspondence to be made.

As noted earlier, the BIND 10 loggers are hierarchical. In practice, the hierarchy will usually be only two levels deep, so each logger will be the child of a parent root logger. If each image in BIND 10 has its own root logger, then a valid correspondence would be:

BIND 9 BIND 10
Category Logger Name
Module Image Name
(= name of root logger)

So a BIND 10 message logged as coming from "b10-resolver.cache" is readily identified as combing from the cache component (category) of the BIND 10 resolver (the module).

Several Points:

  • The BIND 9 logging has a finer granularity for identifying modules, in that each message (if necessary) can be identified with a different module within a program. In contrast, the BIND 10 logging associates a message with a particular program.
  • The BIND 9 category/module is uniquely determined for each message. In BIND 10, the category is determined by the code, the module by the program in which the code is linked. (For example, if a "security" component is linked into both the authoritative server and the resolver, the same message could appear attached to "b10-auth.security" and "b10-resolver.security".)

Message Destinations

As noted earlier, BIND 9 logs to a destination that is matched to the particular combination of category and module; it is possible to do wildcard matches - given category regardless of module and given module regardless of category.

Strictly speaking, the BIND 10 logging hierarchy does not give the former option. To take the example above, the loggers "b10-auth.security" and "b10-resolver.security" are completely separate unrelated loggers with different roots. To enable only "security" across the board would involve enabling it in two separate places.

Last modified 7 years ago Last modified on Apr 26, 2011, 11:22:49 AM