Logging With Intent
One does not write code to please nor impress neither a compiler nor a computer.
If that was the case, society as we know it wouldn’t be properly served by the very own technology that its people help to create.
Instead, we mostly write code in order to create systems with a purpose to help and serve society for the better. Well, at least we try or ought to try to achieve that goal.
When writing code, whether individually or collectively, logic and imagination blend together to solve various problems so as to make the system work. With time, we sometimes forget the reason why a decision, whether a design patterns or an algorithm, was taken for a specific fragment of code. Therefore, so as to avoid letting the feeble mind win, programmers make use of comments to leave a trail of messages explaining the reasoning for specific lines of code. Pretty much like in the story of Hansel and Gretel where the characters leave a trail of bread crumbs behind them so as to find their way home from the enchanted forest.
The enchanted forest. You want to avoid stepping in it.
Using comments is one way to avoid code from taking over your sanity.
Comments are helpful for the programmer whether she’s the author or a contributor. Comments are like annotations that help the reader understand the intent of the author when she wrote the code at that specific time. However, comments are static, because code in itself is static.
However, once that code is compiled and executed, the resulting product, which is a running software, is anything but static. The system lives. The system consumes energy (RAM, CPU cycles, etc.) from its host in order to perform. The system, most of the time, interacts with other systems too. The system is part of a digital community that spans our world’s geographical borders. The system contributes in its digital society by ingesting, transforming and producing data for itself or for others.
With today’s advancements in distributed technologies, a system will rarely live in its own quarters and never go out to talk to its neighbors. That’s pretty rare. Instead, a system will live on the grand, public network known as the Internet. And once the system is living on the Internet, the system has just entered the enchanted forest. Anything can happen. Everything will happen. Code comments aren’t very useful once the system is dynamic; once the system is alive.
This is where logging comes in.
Logging is the communication channel that a system uses to broadcast its interactions and state from within its digital world to ours: the real world. In our world, we have everything available to help the system in any way possible. But unless the system talks to us and tells us how it’s doing and what it’s doing, we’re in the dark. And so is the system. The system needs us to provide it with a good life in the digital world. For us to do that, the system must talk to us. Pretty much like a parent asking her child or teenager to share some information about their life. Or, even better, like a doctor asking her patient how it’s doing to better improve its life.
Whereas the content of a comment is useful to better understand a piece of code, a message being logged from the system has many more implications when not written correctly or completely. A log message that is not clear, nor concise, nor complete can have a negative impact on both the system and the team operating the system, especially when time is of the essence.
Once you’re in the enchanted forest, you have to realize that you’re not in a good place, and you have to get out of it as quickly as possible.
That being said, a good log message should not only be clear, concise and complete for the system’s operators (developers or administrators), but it should also expose both intent and purpose.
When reading a log message, I want to know why an error occurred. How did it occur? When did it occur? Who else is involved with the error? Is there an existing correlation that would allow me to know which other component might be at fault or simply be a victim of the error? In other words, talk to me. Don’t tell me that something went wrong. Tell me why.
If you think about it, it’s not that different with doctors. We can’t simply tell them “my arm hurts” and except them to solve the problem. There’s a Q&A dance that begins between the doctor and the patient, so the former may better understand why the pain is being manifested, how the pain began, what other parts of the body might the pain affect, etc.
Bonus points are awarded when log messages include potential solutions to fix the problem. This can be super important when the software team has a high turnover rate. The next developer might not know how to fix an error. And remember that time is of the essence when an error occurs in production. We need to act fast. We need to act smart. Without good log messages, we can’t do either.
Please be mindful when writing log messages. Whereas comments are mostly helpful to programmers, log messages are useful to everyone: programmers, operators, and sometimes end users. Be mindful of these people. A mark of a true professional is one that also cares about its peers. In short, write log messages with the intent to solve a problem.
Regarding the mechanics or technicalities of writing logs, I strongly suggest favoring structure logs over flat text-based logs. My favorite structure log component when working with .NET is Serilog. Try to find a similar component like it for your development stack. A structure log would provide you with a richer set of metadata for which you can easily and query things you’re looking for. That being said, writing a good log message is important, but enhancing the envelope with a good set of metadata can make wonders when the need arises to solve a problem in production.
So next time you’re writing code for a software, acknowledge the fact that something wrong will occur with the system. Your code might be perfect, but the environment where you code isn’t. Electricity and voltage aren’t always constant. Hard drives might fail. Dependent components might not respond. The Internet is chaotic enough that anyone can guess why an error might have occurred.
By using structure logs and writing good log messages, your software can confidently run in the digital world knowing that someone in the real world would have the appropriate information to set it on the right path again.
A path leading far away from the enchanted forest.
