How to Write Log Files That Save You Hours of Time

Easier debugging using more thoughtful and descriptive errors

Photo by Pietro Jeng on Unsplash.

I need to rant a bit here: The program I maintain at work has many cute quirks. “An error has occurred” is not one of them. This is not just how that error message starts. It’s also how it ends.

Or how about “Information about the error is stored in the server logs,” but there’s no indication of which server actually threw that exception?

This article is about how to write log and error messages that don’t suck.

Do You Really Need This?

Most of this article will be about giving more information. But just for a moment, let’s look at some log messages that can be safely cut. Why? Well, when you have to read through a mile-long log file, you’ll be thankful for everything that doesn’t consume your sanity and focus.

• “All is good” log entries for every single iteration in a loop. As long as I know the program started alright and is maybe now about to enter that loop, all I really care about are errors.
• Random performance logs when I’m not performance testing.
• Logs on every step of a function/calculation. You don’t really need to log “a” and “b” when you’re already logging “a+b=c.”

As I said, it’s better to have more information than you need than too little in most cases, but it’s still worth keeping in mind to avoid falling off the other end.

Please Tell Me What the Error Is

Most exceptions we deal with in daily life aren’t explicitly handled, meaning we often get a stack traceback that tells us exactly what happened, where, and when. That’s fine. It’s not particularly readable, but at least you can follow down to the source.

If, however, you were to catch an exception and use that catch block to then print “Something don’t work yo” to the console without even printing it into the log file, just please don’t. If you write a custom exception handler, then just take the extra minute to explain what the error is. Is it a wrong database entry, like an incorrectly formatted name? Nice, now I don’t have to clone the repo and debug and…