[bind10-dev] Standardised Debug Levels

[Stephen Morris]

Background:
When a message is logged with DEBUG severity, the debug level associated
with the message is also specified.  This debug level is a number
ranging from 0 to 99; the idea is that the higher the debug level, the
more detailed the message.

If debug messages are being logged, the logging system allows them to be
filtered by debug level - only messages logged with a level equal to or
less than the set debug level will be output.  (For example, if the
filter is set to 30, only debug messages logged with levels in the range
0 to 30 will be output; messages logged with levels 31 to 99 will be
suppressed.)

Ticket 1074 is concerned with normalising the logging debug levels so
that a particular debug level have the same meanings in all modules.
I've reviewed use of the debug levels in code written to date, and
propose the following:


Debug Levels
Levels of 30 or below are reserved for debug messages that are most
likely to be useful for an administrator. Levels 31 to 99 are for use by
someone familiar with the code. "Useful for an administrator" is,
admittedly, a subjective term: I've tended to think of it as meaning
helping someone diagnose a problem that they could solve without needing
to dive into the code.  So it covers things like start-up steps and
configuration messages.

In practice, this means that levels of 30 and below are most-likely to
be used by the top-level programs, and 31 and above by the various
libraries.


Level Names
All the modules currently include the string DBG_ somewhere in the
symbolic names used to represent a debug level; some also include the
name of the module, e.g. DBG_COMMANDS, DBG_AUTH_START,
RESOLVER_DBG_INIT.  I would suggest that the system-defined debug levels
start DBG_, and module-specific levels be named DBG_<module>_XXX.


Pre-Defined Values
Although it's possible to categorise a number of the levels, a number
are just specific to a single module; I don't think there is anyway
round this.

I suggest the following common debug levels:


DBG_START_SHUT = 0
Process startup/shutdown debug messages.  Note that these are _debug_
messages, as other messages related to startup and shutdown may be
output with another severity.  For example, when the authoritative
server starts up, the "server started" message could be output at a
severity of INFO.  "server starting" and messages indicating the stages
in startup should be debug messages output at this severity.


DBG_COMMAND = 10
This debug level is reserved for logging the exchange of
messages/commands between processes, including configuration messages.


DBG_COMMAND_DATA = 20
If the commands have associated data, this level is when they are
printed.  This includes configuration messages.


DBG_BASIC = 40
Trace basic operations. (A number of modules already have symbols with
names of the form DBG_TRACE and DBG_TRACE_BASIC etc.)  This level is the
for the highest-level library messages.


Levels 41 - 89
Dependent on the module.


DBG_MESSAGES = 90
Level reserved for very verbose (typically multi-line) output.  This
will typically be used to log item such as the contents of packets
received by and sent from the server.


91-99
Unused for the moment.



Comments?

Stephen