[bind10-dev] log message comments and questions

[Stephen Morris]

On 20/06/2011 18:52, Jeremy C. Reed wrote:
> I looked through all of the log messages. (The HTML document generated 
> in #1012 was 51 pages long.) The following are my comments or questions. 
> I didn't read through much source code to answer yet (and admins should 
> not be expected to read source to clarify log descriptions). I did fix 
> some minor typos, grammar, and case problems and pushed to master 
> (f79a424a36d3a5896c43c5cae5d88d690ecbe90e).
> 
> I don't expect one person to respond to all these points :)

That's a relief!


> (I also posted comments directly related to #1012 in Trac.)

As a background to everyone else, #1012 is a Python script that goes
through all the message files in the source tree and produces as output
a DocBook format file containing all the messages and their
descriptions.  This can then be processed into HTML or whatever other
documentation we want.

I've addressed some general points.  For specific changes, I think we
should raise a set of tickets, one for each message file.


> -	%1(%2) or other format strings may be unclear in admin 
> 	documentation.

This suggests that the introduction needs to be extended.

One thing occurs to me: as part of that ticket, I created a "Logging"
section in the main BIND 10 manual which described the format of the
messages.  Would that be better in the messages document?


> -	missing debug number ("A debug message" or "only appear if debug 
> 	is enabled" is too vague -- when will it be logged at what debug 
> 	level?)

Agreed.  Although 100 debug levels are available, for consistency we
need to define how they are used.  We have discussed the idea of debug
levels of 20 or below being used for messages that might be useful to
SysAdmins and levels above 20 being reserved for "programmer-level"
messages.  Perhaps now is the time to formalise that?


> -	identifiers like RECVTMO and UNKORIGIN are unreadable (spell 
> 	out).  I see this will be discussed in tomorrow's agenda?

Ack.  We just need to decide on a scheme and be consistent.


> -	CCSESSION_MSG -- too many possible errors for one log ID?

This message is generated when an exception is caught.  The text is:

"error in CC session message: %1"

... and the "%1" is replaced with the reason held in the exception
object.  As many exceptions can be caught at this point in the code, it
is inevitable that a single message code will lead to multiple error
messages.

We may want to re-think how we use exceptions.  At present, an exception
is created with a message string (in English) and thrown.  Although
there may be exceptions (no pun intended), an exception is usually
thrown when there is an irrecoverable error in processing.  Perhaps we
want to have a message logged at that point before throwing the exception?


> -	should mes file entries with sorted? (I think they should be in 
> 	alphabetical order.)

Ideally yes, as it makes maintenance easier.  However, a sorted order is
not necessary for correct operation.


> -	All "This indicates a programming error." type messages should 
> 	also say
> 	"Please open a bug ticket for this issue."

We may want to add something to the introduction to the manual to
explain how to open a bug ticket.


> -	MSG_IDNOTFND multiple paragraph description okay?

Yes.  The Python script recognises that a description can contain
multiple paragraphs, making the implicit assumption that the paragraphs
are separated by a blank line.  Within the DocBook output, it replaces
each embedded blank line with "</para><para>", ending the previous
paragraph and opening a new one.


> -	be consistent with British versus American spelling (e.g 
> 	recognize vs. recognise, cancelled vs. canceled, etc.).

Sigh!  As the sole Brit on this project I have the depressing feeling
that we'll end up with American (i.e. wrong) spelling. :-(

Seriously through, as the messages and associated descriptions will be
part of the released documentation, the QA procedures before release
should include going through the message files and correcting spelling,
grammar etc.


> -	some string formating have brackets... use %1 or <%1>  ? or is 
> 	that for a "tuple" only?

The %1 is the substitution string, the "<" and ">" appear in the output
message as is.  From a quick look at the message files, the angle
brackets appear to be used as a form of quoting, e.g. instead of "found
'example.com' in the cache" it is "found <example.com> in the cache". We
probably want some standard for this.


> -        I think there should be separate "DEBUG" severity for
> 	developers too.... now we have debug message useful for admins 
> 	to debug and then other debug message clearly only useful for 
> 	admins (even referring to specific code "the
> 	RecursiveQuery::resolve method...").

See above.


> -	style: some have incomplete / poor grammar for saying it is a
> 	debug message while some have complete separate sentence for 
> 	that.

Partially related to this, I don't see the messages manual as being read
start to finish.  It is something that is referred to when a particular
problem is encountered.

For this reason, the description for each message should be complete in
itself, something that will inevitably lead to a lot of repetition.  So
the description of each message really needs to identify the component
that logged the message.  If it is a debug message, the description
needs to explicitly say that. etc.

Stephen