A device that reports “error” has recognised a problem but has not necessarily helped anyone solve it. Useful diagnostics connect technical state to the decisions an operator, service engineer or developer must make next.
Design for the person investigating
Different users need different information. An operator may need a safe recovery action. A service engineer needs the failing subsystem and replacement decision. A developer needs timing, state and protocol detail. One giant log file rarely serves all three.
Start by defining the likely investigation paths. What questions will each person ask, and what evidence would answer them without reproducing the failure in a laboratory?
Preserve sequence and context
Many device failures are not a single bad value. They are a sequence: a delayed response, a retry, a mode transition and finally a timeout. Diagnostics should preserve enough ordering and context to reconstruct that story.
- Use stable event identifiers rather than relying only on prose.
- Record relevant state transitions and communication outcomes.
- Include monotonic timing where ordering matters.
- Capture software, configuration and hardware versions.
Do not let diagnostics create a second failure
Logging consumes storage, CPU time and communication bandwidth. In a constrained or timing-sensitive system, unbounded diagnostics can alter the behaviour being investigated. Define limits, rollover behaviour and degradation rules deliberately.
Sensitive data also needs control. Device identifiers, location, operator information and payload content should only be captured when justified. Make export and retention behaviour explicit.
Make recovery visible
A system should not only report that something failed. It should make clear whether it recovered, continued in a degraded mode or requires intervention. Repeated automatic recovery can hide a developing reliability problem unless the attempts remain observable.
Test diagnostic behaviour
Diagnostic output is often assumed to work because it appears during development. Treat important events as interfaces: verify that the right information is produced for simulated failures, that storage limits are respected and that support tooling can consume the result.
Build a small, coherent diagnostic model
A useful starting model normally includes events, state, counters and a support snapshot. Events explain what happened. State explains the current condition. Counters reveal frequency. A snapshot collects the versions and configuration required to interpret both.
This does not require a large observability platform. It requires deciding, before field failure, what evidence the team will wish it had.