Skip to content

Capability 005: Health Indicators

Status: Accepted

Context

Before the Robot Operator commands the robot, they want to know whether the Superordinate Controller runs and accepts commands. Today they learn it only from the outcome of a command in the Event Log, or with curl on the command line.

Following the principle Safe when silent of the mission statement, silence must never pass for health: a Health Indicator shows green only while the Superordinate Controller answers that it is healthy.

References

Details

Health Indicators

The Status Pane holds, above the Event Log, the heading Telemetry and one Health Indicator per endpoint. Each shows a lamp and a text next to it. The Health Indicators stand side by side and wrap onto the next line where the Status Pane is too narrow:

Health Indicator Endpoint Green Red Grey
Live /healthz/live running: 200 OK not responding: any other status, or no response within 2 s unknown: before the first outcome
Ready /healthz/ready ready: 200 OK not ready: 503 or any other status, or no response within 2 s unknown: before the first outcome

Timing

Name Value
Health Poll Interval 5 s, the first poll when the page loads
Response timeout 2 s, as for capability 003

Functional Requirements

  1. The Web App polls /healthz/live and /healthz/ready every Health Poll Interval.
  2. Each Health Indicator shows the outcome of the latest poll of its endpoint as given under Health Indicators.

Non-Functional Requirements

None.

Technical Requirements

  1. The lamp colors reach a contrast ratio of at least 3:1 against the background of the Status Pane, as WCAG 2.1, success criterion 1.4.11, requires and user_experience.md demands.

Error Handling

  1. A poll without a response, or with an unexpected status, turns its Health Indicator red; the Web App never shows an earlier green outcome for it.

Out of Scope

  • Entries in the Event Log for a change of health; the Event Log records the outcomes of commands
  • The cause of not ready; /healthz/ready gives none
  • Pausing the polls while the page is hidden

Acceptance Criteria

All criteria except the last run against a mocked Remote Control API, with a mocked clock where time matters.

  1. Page loaded, both endpoints answer 200: Live shows green running, Ready shows green ready.
  2. Page loaded, /healthz/ready answers 503: Ready shows red not ready, Live green running.
  3. Page loaded, neither endpoint answers within 2 s: Live shows red not responding, Ready red not ready.
  4. Page loaded, before the first answer: both show grey unknown.
  5. /healthz/ready answers 503, then 200: Ready turns green ready at the next poll, 5 s later.
  6. The computed contrast ratio of each lamp color against the background of the Status Pane is at least 3:1.
  7. With the Superordinate Controller running on the notebook against /dev/null: both show green; with the controller stopped, both turn red within 7 s (manual test test/manual/remote_control_api.md).

Decisions

  1. The Web App polls; the Superordinate Controller does not push. The health endpoints exist already, and polling needs nothing new on the controller. Consequence: a change shows at most one Health Poll Interval plus the response timeout late.
  2. Each lamp carries a text. Color alone conveys no information to everyone (WCAG 2.1, success criterion 1.4.1). Consequence: the Health Indicator reads correctly without color, e.g. in a screenshot printed in black and white.
  3. No answer means red, not the last known state. A stale green would let silence pass for health. Consequence: a single lost poll turns a lamp red for one Health Poll Interval.