DEV Community

ilya mozerov
ilya mozerov

Posted on

The label is part of the instrument

A status line is a claim. It says what was checked, what was found, and — often without saying so — how recent the finding is. Two lines in a small autonomous system I maintain were accurate under a narrow reading and wrong to the person reading them. Neither failure needed a new sensor or a new threshold. Both needed the words changed.

"Missing" when the real problem was "someone else was here"

A second deployment was promoted and rewrote units that the first deployment generates. The health view reported those units as missing. That word is not false: the checker's "installed" test skips units carrying a different generated marker, so from its point of view there was nothing there. But the reader of the pane could not tell the difference between a unit that had never been installed and one that had been overwritten hours ago by another deployment. A mind had to open a unit file and read its first line to learn the cause.

The repair was small and deliberately additive. The health view now prints a second problem line that names the other deployment and the recovery action. The original ...: missing line is kept byte for byte, because downstream consumers and a regression test use that exact string as their contract. The new line supplies the part the old one never carried: why, and what to do.

This is a pattern worth stealing. When a diagnostic's output is consumed by machines and read by people, and the machine contract cannot change, do not rewrite the string. Add the missing truth beside it. The consumer keeps its stable input; the reader gets the diagnosis. The change was verified on real bytes: collision produced RED with both lines, a bare sync returned GREEN, and a unit carrying a foreign name elsewhere was left untouched. Sixty-seven unit tests passed.

"Camera stale" when the house was simply quiet

On the outer display, a line read camera <room> ... (stale). Both camera signals were green and raw frames were about two minutes old. The age being printed was the age of the newest usable room-activity bucket — a quiet room with no recent motion, not a broken camera. A reader saw a camera fault where there was only a lack of activity.

The fix changed no threshold and no derivation. The line is now labelled activity ..., and a separate status line says the clock is the newest usable motion bucket, not image frame time. Twenty map tests passed, and a live render matched.

The useful distinction is between the quantity a line measures and the quantity a reader assumes it measures. "Camera" named the source; "stale" named the age; neither named the thing that was actually being counted. Once the line said "activity", the quiet room read as data instead of a fault. A display should name the measurement and its clock, because a reader cannot infer either from the green badge next to it.

Writing the meaning down where the line is seen

The same display also had a registry: a short description of what each pane line means. It now points at the module that produces the lines, states what each one measures, and says when it stays UNKNOWN rather than showing a number. A newcomer reading the pane can now check whether "stale" refers to render age, frame age or bucket age without reverse-engineering the producer. The live display shows all three lines together, so the explanation and the thing explained are in the same place.

What both repairs have in common

In both cases the machine was right. The health checker really did skip foreign-marked units; the map really was printing the age of the newest usable activity bucket. What was wrong was the bridge between a check and its reader: the name on the line, and the clock the name implied.

That bridge is part of the instrument. A sensor that measures motion but prints "camera" is a sensor whose output will be misread in exactly the situation that matters — when the room is quiet and someone is looking for a fault. A health view that prints "missing" for a file that is present but foreign-marked will send a person to the wrong cause. Neither is fixed by looking harder at the number.

The durable part, again, is the detector. Each fix came with a test that holds the wording and the behaviour: collision-to-recovery on real bytes for the doctor line, a golden render and twenty tests for the map line. The next time someone reads a status pane and asks "what is this line actually measuring?", the answer should be on the pane — and the test should keep it there.

Top comments (0)