[bind10-dev] Fwd: Re: log message comments and questions

Stephen Morris stephen at isc.org
Wed Jun 29 10:54:02 UTC 2011


This should have been sent to the list as well.

Stephen

-------- Original Message --------
Subject: Re: [bind10-dev] log message comments and questions
Date: Wed, 29 Jun 2011 11:37:59 +0100
From: Stephen Morris <stephen at isc.org>
To: Jeremy C. Reed <jreed at isc.org>

In the sprint planning meeting yesterday, I said that I would raise
tickets for all the issues Jeremy raised in his email of 20 June. I've
now done so.  I also have some more comments (in addition to those I
sent to the list on 21 June):


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 :)
> 
> (I also posted comments directly related to #1012 in Trac.)
> 
> -	%1(%2) or other format strings may be unclear in admin 
> 	documentation.

In my previous reply, I said:

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?

If you think that moving the sections between manuals is a good idea,
can you please raise a ticket for it?


> 
> -	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?)

and

> -        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...").


I've added ticket 1074 for this.  It needs to be done after all the
logging messages have been added: it's then just a question of
categorising what is being logged and updating the values chosen for
each category.

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

This has been addressed.


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

See previous response concerning a discussion we should have over
logging of exceptions.


In the following, I've re-ordered some of the items so as to group them
for tickets.


> - 	CONFIG_CCSESSION_MSG_INTERNAL -- what module "will continue to 
> 	run"? and reword "An unexpected exception was thrown." so is 
> 	useful to admin reading this.
> 
> -	DATASRC_CACHE_CREATE "creating" (upcoming) or "created" (already 
> 	done)?
> 	and what debug level for DATASRC_CACHE_CREATE?
> 
> -	DATASRC_CACHE_DESTROY being destroyed -- does that mean it is a 
> 	long process?
> 
> -	DATASRC_ some say "cache" and others "hotspot cache" -- are they 
> 	really different?
> 
> -	reword DATASRC_CACHE_OLD_FOUND, older instance of cache item 
> 	found, replacing to "replacing existing cache item"
> 	and is it useful if doesn't indicate the name or its value?
> 
> -	DATASRC_MEM_ADD_WILDCARD: reword "Some special marks above each 
> 	* in wildcard name are needed."
> 
> -	DATASRC_MEM_CNAME_TO_NONEMPTY -- what about DNSSEC records?
> 
> -	DATASRC_META_ADD description is not completed.
> 
> -	what is a "meta data source"?
> 
> -	DATASRC_QUERY_EMPTY_CNAME description is not completed.
> 
> -	DATASRC_QUERY_IS_*  "a query" (add "a")?
> 
> -	DATASRC_QUERY_PROVENX_FAIL and others What does "PROVENX" mean? 
> 	(spell out "NONEXISTENCE"?)
> 
> -	reword DATASRC_QUERY_SYNTH_CNAME description
> 
> -	DATASRC_SQLITE_PREVIOUS_NO_ZONE  what is purpose to identify 
> 	preceding name if not in same zone?
> 
> -	generic DATASRC_STATIC_BAD_CLASS ID but description is for a 
> 	specific class

Ticket 1075 to reword the DATASRC messages and the one CCSESSION message.


> 
> -	LOGIMPL_ABOVEDBGMAX and BELOWDBGMIN have typo "DEBGUGn" -- what 
> 	is this string? Where documented? Is this used by admins too? If 
> 	developer only, should message for "BADDEBUG" say to open a bug
> 	ticket?
> 
> -	MSG_BADSEVERITY  allow "NONE" also?
> 
> -	MSG_BADSTREAM incomplete description.
> 
> -	MSG_DUPLNS Where is  $NAMESPACE directive documented?
> 
> -       MSG_DUPMSGID, MSG_IDNOTFND, MSG_NOMSGID, MSG_INVMSGID, 
> 	MSG_NOMSGTXT
> 	(maybe MSG_NSINVARG and MSG_NSNOARG and MSG_NSEXTRARG too?)
> 	(maybe MSG_PRFEXTRARG and MSG_PRFINVARG too?)
> 	maybe there should be a developer option to kill BIND 10
> 	startup if this happens.
> 
> -	MSG_INVMSGID incomplete description
> 
> -	MSG_IDNOTFND multiple paragraph description okay?
> 
> -	should the developer MSG_ problems say to open a bug ticket 
> 	report?


Ticket 1077

> 
> -	NSAS_SETRTT what does "damps out" mean?

It means reducing the severity of oscillations.  Instead of storing the
RTT of the last packet (which could change wildly from trip to trip
depending on network conditions), an averaging is applied to smooth out
the changes.  The term "damps out" comes from "damper", which may be a
British term although Wikipedia also suggests that this is general
engineering usage.

> 
> -	some string formating have brackets... use %1 or <%1>  ? or is 
> 	that for a "tuple" only?
> 
> -	RESLIB_TESTSERV says conflicting debugging and not debug
> 	and " As it should never be seen in      
>    	normal operation, it is a warning message instead of a debug
>   	message." is too verbose, not needed here
> 
> - 	RESLIB_TIMEOUT error will be reported where?
> 
> -	RESOLVER_AXFRTCP says "AXFR request" and "received a NOTIFY" and
> 	RESOLVER_AXFRUDP says "AXFR request" and "received a NOTIFY"
> 	-- well which is it?  (a NOTIFY is a hint to do an SOA serial 
> 	check)
> 
> -	RESOLVER_CLTMOSMALL  does BIND 10 fail to start? then what is 
> 	used? default? minimum?
> 
> -	RESOLVER_CLTMOSMALL  is there a corresponding too large?
> 
> -	Can RESOLVER_CONFIGERR be seperated into programmer error and 
> 	user error with different log ID? Should it say to file a bug 
> 	report?
> 
> -	style: some have incomplete / poor grammar for saying it is a
> 	debug message while some have complete separate sentence for 
> 	that.
> 
> -	RESOLVER_DNSMSGSENT  what details?
> 
> -	RESOLVER_FAILED  does this means that b10-resolver process will 
> 	end?
> 
> -	RESOLVER_FWDADDR why could it appear multiple times?
> 
> -	RESOLVER_FWDQUERY  what checks?
> 
> -	RESOLVER_LKTMOSMALL does BIND 10 fail to start? Or what does it 
> 	use? The default? minimum?
> 
> -	RESOLVER_LKTMOSMALL is there a too large too?
> 
> -	RESOLVER_NFYNOTAUTH how to correspond this to the sender of the 
> 	message?	(log that too?)
> 
> -	RESOLVER_NORMQUERY what checks?
> 
> -	RESOLVER_NOROOTADDR add more details? Should this really be a 
> 	warning? (isn't it just informational and normal?)
> 
> -	RESOLVER_NOTIN  why can't handle other classes in a query? (And 
> 	description should say this is a query?)
> 
> -	RESOLVER_NOTONEQUES typo: "entires"? (entries?)
> 	(while I don't recall seeing it, where is it documented one 
> 	question is limit? even RFC 1035 hints multiple questions could be 
> 	asked.)
> 
> -	RESOLVER_QUTMOSMALL  should it show the minimum? does BIND 10 
> 	fail to start? Or does it use default? or minimum?
> 
> -	RESOLVER_QUTMOSMALL  is there a corresponding too large error?  
> 	(but maybe the existing ID should be for both: out of range.)
> 
> -	RESOLVER_RECVMSG description say "DNS"?
> 
> -	RESOLVER_ROOTADDR why multiple times?
> 
> -	RESOLVER_SETPARAM "interval to resolver" and "continuing to 
> 	resolver"
> 	should be "resolve"?  Too many colons? "resolve gives up" should
> 	be "resolver"?
> 	Maybe this description is way too long -- two paragraphs is too 
> 	long?
> 
> -	RESOLVER_SHUTDOWN, RESOLVER_STARTED are too noisy for default 
> 	logging?
> 	should be debug mode only?

I think that INFO is fine.  These only appear once per session and
provide a record of when it was running.  In a production environment,
these could be helpful in providing uptime statistics and tracking down
service outages.
> 
> -	RESOLVER_STARTING description should mention command line 
> 	arguments?
> 
> -	RESOLVER_UNEXRESP  not enough information? so response doesn't 
> 	match up with an exisiting outbound query (wrong port, address, 
> 	name, class)?
>

Ticket 1078 opened to cover a review of the RESLIB and RESOLVER messages.

Other issues raised in the email:

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

They should be.  I have a Python script that will sort a message file -
if people think that would be useful, I could add it to the tools directory.


> -	All "This indicates a programming error." type messages should
> 	also say
> 	"Please open a bug ticket for this issue."
>
> -	be consistent with British versus American spelling (e.g
> 	recognize vs. recognise, cancelled vs. canceled, etc.).
>
> -	"internal" error should say to open a bug ticket report?

I've not created a ticket for this, as these issues will continually
re-occur.  I thank that reviewers should be explicitly tasked to check
the spelling and grammar of messages and descriptions.

The release process now includes a step to re-generate the message file.
 I suggest that this step also includes a review of the differences
between the old and new files as a one-last check for consistency and
style.  (Jeremy could farm this out to someone else to do in the week
between the sprint ending and the release.)


Stephen



More information about the bind10-dev mailing list