Jihye's Blog

Photo by David Pupăză on Unsplash

Logging on the server side felt simple to me at first, but as I spent more time working on real systems, it quickly became one of the hardest parts of building something reliable.

Through experience, I’ve found that good logging isn’t just about adding more logs. It’s about figuring out what actually matters, when it matters, and how much is too much.

I’ve run into both extremes. Too little logging left me completely blind during incidents, with no clear way to understand what went wrong. On the other hand, too much logging created so much noise that finding the real issue became just as difficult.

Over time, I’ve started to form a set of principles from my own work that help me strike a better balance, keeping logs useful for debugging without letting them get overwhelming.

1. Log the Entry Point of Every Flow

Before your logic branches into multiple paths, log the entry point of the process.

This gives you:

• A clear starting point for tracing execution
• A reliable anchor when reconstructing flows during debugging

Without this, you’re often guessing where things began.

2. Make Skips Explicit (with Context)

Whenever your system decides not to do something, log it.

Silent skips are dangerous. They create confusion because:

• Nothing breaks
• But something doesn’t happen

Always include full context when logging skips:

• Why it was skipped
• What conditions led to it
• Relevant identifiers

3. Log Both Success and Failure

It’s tempting to only log failures, but success logs are just as important.

Why?

• They confirm expected behavior
• They help compare “working” vs “broken” flows
• They make metrics and auditing easier

A system that only logs failures tells an incomplete story.

4. Warn on Unexpected Input Shapes

If input doesn’t match expectations but the system can still proceed, log a warning.

Examples:

• Missing optional fields
• Unexpected formats
• Partial data inconsistencies

This is your early warning system before things escalate into errors.

5. Make Asymmetric Rules Visible

If your system applies non-obvious rules (especially ones that aren’t symmetric), log them.

For example:

• Special-case handling
• Priority overrides
• Hidden business logic

Instead of silently applying these rules, surface them in logs. This will help future you (or your teammates).

6. Aggregate Failures When Needed

In systems that trigger multiple downstream actions (e.g., batch jobs, fan-out events), logging each failure individually isn’t enough.

Add:

• A summary log of aggregated failures
• Context about the overall operation

This helps you answer:

“Did the whole operation succeed?”, not just “Did individual parts fail?”

7. Support Two Levels of Logging

Sometimes you need both:

• High-level logs → overall job or request outcome
• Detailed logs → step-by-step execution

Design your logging so you can:

• Stay at a high level for normal operations
• Zoom into specific jobs when debugging

This layered approach prevents noise while preserving depth.

8. Keep Logs Structured and Consistent

Every log entry should include a minimum consistent set of fields, such as:

• id (request ID, job ID, correlation ID)
• source (service or module name)

Consistency enables:

• Reliable filtering
• Easier querying in log systems
• Better observability across services

Structured logging (e.g., JSON logs) is a big win here.

9. Use the Correct Severity Levels

Not all logs are equal. Misusing severity levels makes logs harder to trust.

A simple guideline:

INFO → Normal system behavior

WARN → Recoverable or expected issues (e.g., bad input)

ERROR → Unexpected failures or system misconfigurations

If everything is an error, nothing is.

10. A Few Practical Tips

• Avoid logging sensitive data (tokens, passwords, personal info)
• Prefer context over verbosity. A short, meaningful log beats a long useless one
• Think in queries: “How would I search for this problem later?”
• Use correlation IDs across services to trace distributed flows
• Periodically review logs, logging quality degrades over time if left unchecked

Final Thoughts

Good logging is less about volume and more about intentionality.

It’s a design problem, not just an implementation detail.

When done well, logs become:

• A debugging tool
• A system narrative
• A safety net during incidents

When done poorly, they become noise.

The goal is simple: Make your logs tell a clear, truthful story about what your system is doing without making you work to understand it.