Document the LOG format

[ryankeairns]

Based up conversation in #1012 , the consensus was that the two-letter LOGKEY format was unclear. Options discussed included expanding the LOGKEY format and/or providing clear documentation on the acronym definitions.

[reset]

I dropped a comment in that thread but I'll repost it so we can continue the discussion here:

The purpose of the two character log key isn't for informing users, but developer access and debugging. We are supposed to be using these to identify which module a log even is coming from without needing to specify the full path plus crate name of the module in the log output. This is much like the way we log error messages in the servers with a very similar format.

I would stick with two or three character log prefixes, expanding them is going to clutter the log and I don't think it makes things any easier to track down.

[ryankeairns]

Sounds good - seems like we just need to document this somewhere logical for people to decipher the messages (if we haven't already).

[adamhjk]

Lets document it and keep it to two characters. They are troubleshooting keys, and the expanded version doesn't make that better - it makes it worse. :)

[adamhjk]

Just in case I wasn't clear here - the two character thing has a good reason. It walks the line between crazy verbose logging with specific modules and line numbers, and the ability to determine where in the code base the log line comes from. Two characters is short enough to not be intrusive, and makes the output much easier to parse when we're trying to understand what it means.

So this PR should become "document the log format", not "change the behavior" - because the behavior is good.