The services roster has no read

Table of Contents

This page is a capture in the inbox bucket of the product backlog — a pre-sprint idea, not yet pulled into a sprint as a story.

1. What

The services screen shows what the installation runs as a roster: one row per expected instance, with a state word for each — running, stopped, missing — so a service that stops keeps its row and a service that never reports shows as missing rather than absent (See the running services). The screen needs two reads and neither exists.

The roster itself is a code-generation model. projects/modeling/service_registry.org lists every service, its replicas, its enabled flag and its startup dependencies, for the deployment tooling to generate from. No operation serves it, so the screen can only draw what reported, and the expected-but-absent row cannot exist.

The state beyond running hangs on the same gap. Running is answerable today: a sample arrived within five minutes. Stopped and missing are not. The thing that knows an instance was stopped is the service manager — the one compass services status asks — and it serves no screen. The candidates: a read of the registry, so the expected rows and the replica counts exist; and either a state read or the latest sample per instance at any age, so a quiet instance keeps its row with the age of its last report.

2. Why

An operator's question is as much what is missing as what is running. A screen drawn from samples alone answers only the second, and it fails in the worst way: the shorter the list, the less the reader can tell. The registry already holds the truth a screen needs — the expected services and their replica counts — and it is one read away.

3. Resolution

Done in task Serve the services roster, under story Implement the operations journeys in ores.web. Both candidates became reads.

The registry's expected services reach the database the way its IAM identity already does: an archetype in the ores.sql.service facet renders every enabled entry into ores_telemetry_expected_services_tbl with its replica count. telemetry.v1.services.roster then answers with one slot per expected instance. The newest instances to report, at any age, fill the slots; an instance that reported within the running window is running, one that reported earlier is lost, and a slot nothing fills is missing. A restart's leftover instance fills no slot, because an instance id is new at every start.

Heartbeats cannot tell a service somebody stopped from one that fell over, so the roster says lost rather than stopped. Telling the two apart is Record service starts and stops. Both liveness reads now check telemetry::samples:read.

Verification lives on the task.

4. References

  • projects/modeling/service_registry.org — the registry: every service, replicas, enabled, dependencies
  • projects/ores.telemetry/modeling/ores.telemetry.service_samples.org — get_service_samples, the reporter side
  • projects/ores.compass/ — compass services status, the service manager's only surface today

5. See also

Emacs 29.3 (Org mode 9.6.15)