One of the fit-and-finish issues all systems developers need to address is the text of log messages. This is a log message style guide.

Once your product ships, it will be in customers' hands. They will run it on their machines. You won't be around, and neither will your debugger. Log messages could be a big part of your customer's experience with your product, especially when something goes wrong. They could also be a big part of your experience with fixing problems at customer sites.

Be professional

These log messages will be some poor customer's first view of you after a problem occurs. Make sure the messages make the customer feel better about the product, not worse. Part of it is writing professional English (or whatever language), and part is having the right attitude in the text.

Simply being consistent in your log messages will go a long way toward making them seem professional and authoritative. Below I give guidelines for wording, punctuation, and so on. Even if you don't use these guidelines, pick some rules, and follow them.

  • When logging a problem performing an operation (for example, reading a record), say what couldn't be done:
  • GOOD:    Couldn't read record.
    BAD:     Something happened?
    BAD:     Wow!!!
    BAD:     Oops.
  • When announcing an operation (either an informational or trace message), say what is going to happen.
  • GOOD:    Reading transaction log.
    BAD:     I think I'll read the transaction log.
    BAD:     Step 17a
  • Use normal sentence capitalization and punctuation.
  • GOOD:    Couldn't open storage file.
    BAD:     Couldn't   open storage    file
    BAD:     Couldn't Open Storage File
    BAD:     COULDN'T OPEN STORAGE FILE
  • Don't be flip. These message may be read by some customer pulling their hair out over a problem that's making their day a nightmare. The last thing they want is to feel like you're making fun of them from the comfort of your cushy cubicle.
  • GOOD:    Couldn't read record.
    BAD:     I wish I had been able to read that record
    BAD:     Wow!!! No record!
    BAD:     Oops. Record on floor.

Think like a support staffer

As a developer, remember that you will be debugging problems with only these log messages to go by. Something will go wrong at a customer site, and you will be sent a log session (more than likely incomplete). You will not have a debugger, you will not have access to the machine. You will have your log messages. Make sure they will be helpful to you.

  • When writing a message to the log, if you have more information (for example, an exception), use it in the message. Don't forget to supply the punctuation needed to make it look right:
  • GOOD:    Couldn't save data: corrupt lock record
    BAD:     Couldn't save data
    BAD:     Couldn't save datacorrupt lock record
  • For punctuation between parts of the message, use a colon:
  • GOOD:    Couldn't save data: corrupt lock record
    BAD:     Couldn't save data | corrupt lock record
    BAD:     Couldn't save data <corrupt lock record>
  • Provide information you think the reader of the message will need. Don't forget that the reader may be you six months from now. Try to answer his next question:
  • BAD:     Couldn't read vital information
    GOOD:    Couldn't read vital information: UserName
    BETTER:  Couldn't read vital information: UserName on document #2345a1

Use a real log

Many programming environments provide logging facilities. If you have one, use it. If you don't have one, search the web for one you can use. If you can't find one, seriously consider spending two days to write one. They provide useful features like timestamping, run-time selection of logging detail and facilities, options for where to log (system console, log file, system event log, etc).

Python has the logging module described in PEP 282, and now standard as of Python 2.3. Java has Apache's log4j. An example C++ facility is available from CodeProject.

Use your log now

As developers, we have a rich environment in which to experience our code: the debugger. When a problem occurs, our first impulse is to fix it: dive into the debugger, understand what's happening, fix the code, recompile, no more problem. Except there could still be a problem: what if the same bug had happened at a customer site? Suppose you had to fix the bug with only the log messages to guide you? Would you have been able to?

Next time a bug appears, don't jump into the debugger. Read the log. What did it tell you? Think hard about what information could have been presented there but was not. How could you make it more useful?

The first thing you should do is change the log to provide the information (ubiquitous stringification can help a great deal here). Run the code again (with the bug). Make sure that the log really is better. Then you can go ahead and fix the bug.

Of course, it is impossible to make logs rich enough to be a complete replacement for a debugger. And maybe you don't want to put effort into improving your log. But using the log now will at least give you a sense of what your customers and support people (and likely, you) will be experiencing when the product is in the field.

See also

Comments

[gravatar]
Tom Harris 1:36 PM on 19 Apr 2009

You've certainly addressed the most important part of log messages: the content. But if you're offering a style guide, there are other aspects that help the maintainer and supporter of the software. For example:

1. Metadata: Severity, type of message, location in the code and in the functionality.

2. Format: Fixed column widths and closed lists of values so that a standard or custom log viewer has an easy time to display, search, group, filter.

[gravatar]
Steve Booth 2:30 PM on 20 Jul 2010

Along with Tom, I'd add the proviso that Every message should be unique. Much easier to identify problem code.

Add a comment:

name
email
Ignore this:
not displayed and no spam.
Leave this empty:
www
not searched.
 
Name and either email or www are required.
Don't put anything here:
Leave this empty:
URLs auto-link and some tags are allowed: <a><b><i><p><br><pre>.