In my previous jobs I also had to analyse log messages for which I did
not have the code readily available. Besides intentionally idiotic
messages like "trouble in paradise", I had my fair share of message
that made me grind my teeth. They read like:
could not open file
could not connect
error parsing
These were the full texts, seriously. Why does the idiot not list the
file it can't open? Why can't they just tell me which crap they can't
parse? Had the information been in the log message, often-times the
support case wouldn't even have reached my inbox. The customer could
have fixed it in a minute by providing the file missing or fixing the
string to be parsed.
To avoid the above I came up with rules for what a good logging
message should tell us. This applies to warnings and errors, not so
much for purely informational message.
What went wrong? This is the easy part shown above.
What is the object or item making the problem? This is often a
file, a host:port combination, a missing configuration item, a
wrongly formatted string. When naming this object in detail, problem
fixing can be trivial. In the code it can be tedious: consider
passing an input stream around and deep down in some parser you get
a premature EOF. To log the file name down there, you would have to
pass the file name around alongside the input stream. Or you make
sure the exception bubbles up to catch it in just the right place
where you know the file name and log it there. It may need an
additional line of code or two, but its worth it.
What are the consequences? The message should provide minimal
information about what this means for the operation of the
software. "Cannot proceed, will crash", "ignoring malformed line",
"using default xyz" are some examples. In the latter, don't just
write "using default"!
Log messages are also customer communication. So as a fourth rule:
avoid developer vocabulary. Though I came across only one example. In
Java land we might talk about "resource", whatever it is. Other people
know this rather as file or something.