Sometimes, printing things out is the simplest debugging technique we can use. And then, when we forget to take the print statements out, we call the output our logs.
That’s a mistake. Logging shouldn’t be an afterthought. It’s a core piece of diagnostic tooling. Logs are so cheap to integrate that they are almost always an extremely high return-on-investment feature. Your logs should be treated as first-class features warranting all of the attention to detail that you give to your more user-visible features.
Benefits of Logs
With logs, you can learn:
- If you have a problem
- Where in the code the problem is being triggered
- How many people are seeing the error
- What data is causing problems
You shouldn’t wait to find out about a problem until a customer emails you about it. Most of them won’t; so by the time you hear about it, the problem will have affected a large number of people. For the most frequent problems, you should have all the information about them before your customers can pick up the phone.
Now, that isn’t controversial at all—after all, there are numerous exception notifier services out there, and many projects will proactively notify on those things. However, it’s easy to forget about the logs if your software is distributed to users (since there isn’t the one main deploy that you can monitor). This is where it’s most useful to have some logs, because you may not have access to any other information.
Tips for Logs
Here are a few suggestions to ensure that you get valuable logs when your users report an error:
- Remember that important domain transactions don’t necessarily correlate with framework transactions. That is, “creating an invoice” (an important transaction in a business domain) isn’t necessarily a one-to-one correlation with the HTTP request of “POST /invoices.”
- Include context: What class/file am I in? Java’s packages are a great default, but you should make sure that whatever format you use, you can take a log from the customer and jump straight to wherever the log line comes from.
- Write your messages as if they’re for your customers first and you second. You’re still an important consumer, but if you write your diagnostics with your customers in mind, you’ll find yourself being more descriptive and polished.
- Avoid profanity. See above–if you’re not the consumer, it’s probably not a good idea.
Remember that the only software people don’t have trouble with is software that people don’t use. There’s no reason to make things harder on yourself by making those problems harder to diagnose.
A Smart Investment
And don’t forget: Your customer will almost never ask for you to build good diagnostics. But they’ll certainly appreciate it when you can detect, diagnose, and resolve errors quickly.