The Lost Art of Writing Great Log Messages

When everything is running smoothly, log messages often go unnoticed. But the moment stuff breaks, logs are usually the lifeline. In those rough moments, a great log message can be the difference between a quick fix and hours of guesswork.

I spend a huge chunk of my work debugging and maintaining codebases that I've never touched before. And I can tell you that writing good log messages isn’t just about documenting code. It’s about helping the next engineer—or your future self—quickly understand what's happening and how it's happening, especially during tense times.

Why Good Logs Matter

Logs are the extension of documentation. They explain the flow of your system, the decisions made at each step, and the points where things went off track. If a log message is too vague like “We did something here,” it offers little to no value and sometimes can cause confusion. Logs should give enough detail to explain what happened and hint at how it happened, especially when someone can’t look at the underlying code. This usually becomes very clear when you are trying to fix a production system that you are not familiar with.

Moreover, when everyone can read and understand the messages, it’s easier to divide tasks and assign fixes. Without good logs, people might rely on trial and error, which wastes time and introduces more confusion.

Choosing the Right Log Level

Debug logs are for deep dives. They reveal internal state and detailed activity, but they should only be enabled when you need that level of insight. If debug logs are always on, they can bury important info under irrelevant details. So, the “why” behind using debug logs is to clarify complex processes when necessary—but not to spam your system with noise.

Debug logs should act as an online production "debugger," allowing you to follow the execution step, understand the call stack, data flow, and the application state. But it's not always on. You only use a debugger when you need to.

On the contrary, info logs are always on—they sit at the heart of normal operation. They mark meaningful events you’d want to see in day-to-day usage. The reason you have info logs is to confirm expected behavior.

Error logs exist to highlight failures. They deserve extra context—like what was being attempted, which process was affected, and what might have caused the error. The point of error logs is to guide you toward a fix as soon as you spot them.

How to Write Them Well

As a general rule of thumb, logs should be written for the next engineer.

This means every log message should be self-explanatory, provide value, be packed with context, and consistent with other messages. Here are some guidelines I follow to write good log messages:

Descriptive and Direct

Every log line should explain the event in a short, direct way. This helps anyone scanning your logs see the bigger picture right away.

Include Relevant Data

If an error happens, provide the relevant values. This extra context can save hours when tracing issues. Logs—especially error and debug logs—should allow you to "reproduce" the issue.

Avoid Filler

More log lines aren’t automatically better. Messages that don't add value or provide direct explanation for an operation should be deleted.

Stay Consistent

Pick a format for your messages and stick to it. Consistency makes logs easier to skim and parse. Human brains are great at pattern recognition. When scanning through thousands of log messages, even a tiny change in the format can catch your eye. This can't happen if you are not consistent.

Final Thoughts

Writing efficient log messages is a great practice that directly impacts how quickly issues get resolved. It’s a mandatory extension of your documentation and a critical component of building predictable and maintainable software. By investing the time to write clear, context-rich, and purposeful logs, you're saving your team (and often yourself) valuable hours in debugging and keeping your systems understandable, maintainable, and reliable.