NEVO
All notes
Operations

Write logs for the next question

3 minute read

Good logs explain what happened without requiring a reader to reconstruct the whole application.

The most useful log entry is rarely the longest one. It is the entry that answers a concrete question: which operation was affected, what decision was made, and what happened next?

Start with an event

Describe the event in plain language and put changing details into structured fields. A stable event name makes it possible to count and compare occurrences without parsing sentences that change with every release.

For a failed downstream call, useful details include the dependency name, elapsed time, attempt number, and error category. A full request body is usually less useful and may contain information that should never reach a log.

Carry context carefully

A request identifier connects related events. Pass it through the work you own and include it at important boundaries. Keep it distinct from an authentication token, session secret, or other value that grants access.

A correlation identifier is a reference, not proof that two events are causally related. Background work, queues, and fan-out can require additional operation identifiers to make the relationships clear.

Use severity to guide action

Normal retries do not always need an error-level entry. An expected rejection may be useful as a count without being useful as an alert. Reserve the loudest signals for conditions that need attention.

Likewise, avoid reporting the same failure at every layer. Let the layer with enough context explain the outcome, and use lower-level events only when they add a different fact.

Read a failure from beginning to end

Before calling a logging change complete, trigger a representative failure and read the resulting entries. Can you distinguish a slow dependency from a rejected input? Can you find the final outcome? Is any sensitive data exposed?

Logs should reduce the number of questions an operator has to ask. If an entry only says that something went wrong, it is a useful starting point for the next revision.


Explore the notebook