Stop Writing System Logs For Your Mental Model – Write For Your User’s Instead

Posted on by




The Mental Model Mismatch in Logging

Your logs are telling the wrong story.

You’re documenting your understanding of the code – the functions, classes, and internal states. But your users (developers, operators, SREs) need to understand their system – the applications, services, and business operations.



The Symptoms

You see this everywhere in production logs:

# Developer mental model
logger.error("ImagePullBackoff for pod webapp-7f8d9")
logger.error("HTTP 500 at /api/v1/process")
logger.error("Database connection timeout")

# vs. User mental model
logger.error("Application 'webapp' cannot start: container image unavailable")
logger.error("Payment processing failed: internal server error for order #12345")
logger.error("User authentication service unavailable: database unreachable")
Enter fullscreen mode

Exit fullscreen mode

Both are clear. Both are professional. But only one answers: “What’s broken, for whom, and what do I do?”



The Shift

From documenting code flow → To telling the service story

Stop thinking: “What’s happening in my function?”
Start thinking: “What business operation is failing?”

From isolated events → To correlated journeys

Every log should answer: “Which user request/service operation does this belong to?” Use correlation IDs religiously.

From technical states → To business impact

“Database connection failed” → “User signups blocked: authentication database unavailable”



Practical Shift

Before writing a log, ask:

  1. Who will read this at 3 AM?
  2. What do they need to know about the service, not the code?
  3. What action should they take?

Your logs shouldn’t document your codebase. They should document your service’s behavior for the people who keep it running.

Write for the human debugging, using the system, not the humans who are developing it.



Source link