[krbdev.mit.edu #2147] Debug output hooks need to be added to support Windows Help Desk

[Jeffrey Altman via RT]

>From Ken:

The list below was originally entitled "some thoughts on logging", and I
was going to work on it a bit more before sending it, but since Jeff has
brought it up....

I agree with Sam that 32 flags might not be enough.  I think we could
use an array and an offset into it, with each flag being the offset, not
a mask.  Initially, it probably would only have one element, but we
might expand it quickly.  libkrb5-tgs, libkrb5-as, libkrb5-ap, kdc-tgs,
kdc-as, kdb, kdb-db2, kdb-mysql, krb524, krb4-tgs, krb4-as, krb4-ap,
libkrb5-sendto, crypto, fake-getaddrinfo, gsssapi, pty, I'm sure we
could come up with other cases where we want to debug only one aspect of
the code.

The syslog approach of having a "level" orthogonal to the "facility"
seems useful.  We could send serious problems (e.g., keytab format
errors) to syslog by default, leave informational and debugging messages
off unless requested.  Might we want another separate flag for whether
or not hex dumps should be logged?

I think I'd like to have the option of a textual form for specifying the
parts of code for which debugging is enabled.  Numeric is okay, but if
we do only numeric, we should at least make sure to support a hex
option, and support more than 32 flags.  (Arbitrary hex string to fill
an array of unsigned char?)

Some other random thoughts:

 * A printf-like function that is Kerberos-aware would be handy.  I did
something like that for sendto_kdc, with %E for krb5_error_code
(displays as numeric and text), %m for an errno value (like syslog, but
passed in instead of global), %F for select file descriptor set (a
structure I set up in that code, in/out/except fd sets plus timeout),
%s/%d/%p like printf but without widths, %t for struct timeval, %A for
struct addrinfo, %D for krb5_data (raw dump).  Add more, like principal
name display etc.

 * compile-time checking for the debug calls would be nice, but
conflicts with the above

 * "dump out this block in hex and ascii"; I've written that some 3 or 4
times now.  For non-ascii dumps, probably want two forms, one for short
byte strings, all in one line, maybe without spaces, and another for big
blocks, with line breaks and maybe offsets and such.

 * should be able to compile in by default, leaving it disabled (but we
currently dump the enctype list in KDC requests?)

 * logging for administrative reporting and debugging are not the same
thing, though they can probably use some of the same code.  (Perhaps we
should log enctype lists separately from other data in KDC requests?)

 * switching between stderr and syslog and log file is a nice option;
select through config file?

 * log file name and line number, maybe function name as well if
available; try to do it through macros so as to require much less typing
to instrument code; could be as easy as #define HERE
__FILE__,__LINE__,__func__/NULL

 * annotate lots of error returns in libraries, especially when multiple
causes are possible

 * be able to switch on and off logging for various parts of the code
(crypto, kdc, libkrb5, gss, maybe finer control?).  maybe multiple flag
variables, maybe multiple bits in a vector.  Probably test at call site
via macro or inline function?

 * log "e-text" field in "generic error" case

 * short name for convenience, even if via macro, since we'll be typing
it a lot, and calling it with long strings that don't look good when
they wrap