Why My Logs Used to Be Useless (And What I Changed)

For the first year or so of writing backend code, my logs looked something like this:

checkout failed for user 8821 - timeout after 3 retries

That looks fine, right? It reads like a sentence. A human can understand it. The problem is I only ever thought about the log message from my point of view, sitting there watching it scroll past in a terminal. I never thought about what happens when there are a hundred of these lines, from five different parts of the app, all mixed together, and I'm trying to find just the ones about this specific user's checkout.

Turns out, a sentence is a nightmare to search through. You end up guessing keywords and hoping.

The night that changed my mind#

We had an outage. Checkouts were failing for some users, not all of them, and nobody could tell me which ones or why. I opened the logs and started scrolling. And scrolling. Every log line was a slightly different sentence, so I couldn't just filter by "checkout" and "user id" — I had to read almost every line by eye, like I was looking for a specific paragraph in a book with no table of contents.

It took way longer than it should have. And the fix, once I found it, was small. The lesson stuck with me a lot longer than the bug did.

What I do differently now#

Instead of writing my logs as sentences, I write them as a small list of facts — almost like a form you fill out. In plain terms, instead of describing what happened in a full sentence, I just record: what happened, who it happened to, and when.

{
  "event": "payment_timeout",
  "user_id": 8821,
  "retries": 3,
  "time": "2026-05-10T03:14:02Z"
}

It looks a little colder than a sentence, sure. But now I can actually search for it. "Show me every payment_timeout for user 8821" is a real question I can ask, instead of a hope that my search words happen to match someone's sentence from three months ago.

The other thing nobody tells you#

Logs pile up. If you never clean them out, they just keep growing until one day your server runs out of space to store them — usually at the worst possible time, because that's how these things go. I learned this the hard way too: set a limit on how long you keep old logs before you need one, not after.

That's really it. Two small habits — write facts, not sentences, and don't let them pile up forever — and debugging went from "read everything and hope" to "ask a direct question and get an answer." Nothing fancy, just a different way of thinking about who's going to read this line of text at 2am someday: not you, a tired stranger. Write it for them.