Coverage
Monitoring coverage health: assigned and desired replicas, quorum, and under-replication.
What coverage answers
Coverage is monitoring coverage health: whether a monitor has the replication and the evidence its assurance level asks for. It is a different question from endpoint health — whether the monitored thing is actually up — and Pinggy reports the two separately. See States for why these are kept apart.
Assigned, quorum, and desired
Every monitor's assurance level names two numbers — desired replicas (how many nodes it asks to be assigned to) and quorum (how many votes are needed to settle a state) — see Consensus for the table of levels. A monitor's actual placement gives it some number of assigned replicas, which may be fewer than desired if the fleet does not currently have the capacity or eligible nodes to place all of them.
The two coverage conditions
Coverage is read from these three numbers, and it names two conditions that are related but distinct:
- Under-replicated — assigned replicas are fewer than desired replicas. The monitor is being watched by fewer nodes than it asked for.
- Cannot reach quorum — assigned replicas are fewer than the quorum itself. No evaluation of this monitor can be conclusive until the fleet grows or the assurance level is lowered.
These are not mutually exclusive, and a monitor can be in neither, either, or both at once:
| Assigned | Under-replicated? | Cannot reach quorum? | Reading (standard assurance: desired 3, quorum 2) |
|---|---|---|---|
| 3 | No | No | Fully covered. |
| 2 | Yes | No | Under-replicated, but still quorum-capable — its answers are conclusive, with less redundancy behind them. |
| 1 | Yes | Yes | Under-replicated and unable to reach quorum — no evaluation of it can be conclusive right now. |
A monitor may remain quorum-capable while under-replicated. Losing a replica does not, on its own, make a monitor unable to answer — it can still reach a conclusive UP or DOWN with the votes it has, just with fewer of them than its assurance level asked for. Whether insufficient fresh evidence actually produces UNKNOWN is the consensus rule in Consensus, not the coverage reading itself; the two are related, because fewer assigned replicas makes UNKNOWN more likely, but they are not the same statement, and Pinggy reports them separately rather than conflating "under-replicated" with "UNKNOWN."
Capacity-blocked
A third condition, independent of the two above, applies when the fleet's reconciler could not place a monitor's replicas at all — a fact about current fleet capacity, not about that one monitor's evidence. A capacity-blocked monitor carries the reconciler's own stated reason.
Placement quality
Separately from replica counts, Pinggy reports how well a monitor's assigned nodes are spread across distinct sites, regions, and providers, from worst to best:
| Quality | Meaning |
|---|---|
| INSUFFICIENT | Fewer assigned replicas than desired, or unable to reach quorum. |
| DEGRADED | Fully replicated, but concentrated rather than spread. |
| GOOD | Spread across more than one site, region, and provider. |
| EXCELLENT | Spread across at least as many distinct sites, regions, and providers as desired replicas. |
Placement quality is a redundancy measure, not a health measure: a monitor can have EXCELLENT placement and report DOWN, and INSUFFICIENT placement while still being UP on the evidence it has.
Related concepts
This article is part of this repository and is served by the same binary, so what you read here is the documentation for the version you are running.