Stop Writing System Logs For Your Mental Model - Write For Your User's Instead

Source: Dev.to

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.

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")

# 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")

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

From documenting code flow → To telling the service story

• Stop thinking: “What’s happening in my function?”

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.”

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 the system, not the humans who are developing it.