← BlogBen LaiSubscribe via RSS ↗

Logs are a user interface

Logs are not exhaust. They are the interface your future operator uses when every other interface has stopped being enough.

The log line is written for a person under pressure. That is the standard. Most logs fail it.

request failed is not a log. It is a confession that the system noticed pain and refused to be helpful. Which request? Which customer? Which dependency? Was it retried? Did it mutate state before it failed?

The problem is that engineers write logs while they still understand the code. Operators read logs when that context is gone. The log has to carry the context across time.

A useful log line

A useful log line has:

  1. A stable event name. Not prose that changes every refactor.
  2. The actor and object. User, account, job, invoice, deployment.
  3. The decision. Accepted, rejected, skipped, retried, rolled back.
  4. The reason. One machine-readable code, one human-readable phrase.

That sounds verbose until the incident. Then it sounds cheap.

Logs are a user interface with no designer, no PM, and no usability test. Add one. Read your own logs cold once a month. If you cannot reconstruct the story, neither can on-call at 03:00.