Write the log line for the person who is scared

Think about who actually reads a log line. It is not you, at your desk, with the file open. It is someone at three in the morning who did not write this code, has been awake for twenty minutes, and is afraid that whatever they do next will make it worse. That is the reader. Almost nothing we log is written for them.

We log for the author. "Entering handler." "Cache miss." "Retrying." Each of those is a note to a person who already knows the shape of the system. To the scared reader they are noise between them and the one line that matters.

A line written for the 3am reader answers three things without being asked: what was being attempted, what happened instead, and what identifier lets me find the rest of this story. "Failed to charge order ord_8812: card declined (insufficient_funds), 2 of 3 attempts" does all three in one line. "Payment error" does none of them, and it is the line we ship.

The second habit is harder: log the decision, not just the outcome. When code chooses a branch for a non-obvious reason, say so. "Skipping sync for tenant 41: last sync 14s ago, min interval 60s" turns a mystery into a sentence. Half of the incidents I have sat through were someone slowly reconstructing a decision the code could have simply stated.

And be honest about severity. If an error line does not mean someone should act, it is not an error, and every time you cry wolf you make the real line harder to find.

The test I use before shipping a log line: if this fires at 3am, and the person reading it has never seen this file, does the line tell them what to do next? If not, it is a note to myself, and I should write it for them instead.