[bind10-dev] log message comments and questions

[Jeremy C. Reed]

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.

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

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

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

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

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

-	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

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

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

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

-	NSAS_SETRTT what does "damps out" mean?

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

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

	(10:05:06) stephen: This can be done.  Assign low debug
	levels (say < 20) to debug messages targeted to admins,
	and use higher numbers for more detailed developer-level
	debug messages.  If developers need the detailed debug
	messages, they probably need the admin-level debug messages
	as well.
	(10:07:06) jreed: okay. We will document that and follow it.
	(10:08:43) stephen: It may need some tinkering in the source
	code.  The debug level of the message is set at the point
	the message is logged, so the values in some LOG_DEBUG
	statements may need changing.

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

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


  Jeremy C. Reed
  ISC