States
What UP, DOWN, DEGRADED, UNKNOWN, and PAUSED mean, and how a monitor moves between them.
Three separate questions
Pinggy answers three distinct questions about a monitor, and keeps the answers separate rather than folding them into one status:
- Endpoint health — what the assigned nodes' probes actually observed. This is the consensus state: UP, DOWN, DEGRADED, UNKNOWN, or PAUSED. See Consensus for how votes become this state.
- Monitoring coverage health — whether the monitor has the replication and evidence it needs for its consensus to mean anything: assigned replicas against desired replicas, and whether quorum can be reached at all. See Coverage.
- Platform or node health — whether the infrastructure carrying the monitor is itself healthy and participating: a node's own ONLINE, STALE, or OFFLINE status. See Enrolling nodes.
A single word like "unhealthy" would erase these distinctions. Pinggy states each one by name.
The five consensus states
| State | Meaning |
|---|---|
| UP | The evidence supports the endpoint working. |
| DOWN | The evidence supports the endpoint not working. |
| DEGRADED | The evidence disagrees — some assigned nodes report UP, some report DOWN — and neither side has enough votes to settle it. |
| UNKNOWN | There is not enough recent evidence for a conclusive answer, or the monitor has not been evaluated. |
| PAUSED | The monitor is disabled. It is not being asked whether the endpoint works. |
The freshness rule
A monitor's state is its last stored consensus — but only within a bound. If the stored consensus is older than the monitor's freshness budget, the state is reported as UNKNOWN, whatever it last said. The budget is 3 check intervals, with a floor of 5 minutes and a ceiling of 30 minutes, so a 30-second monitor is not marked unknown over a few seconds of scheduling jitter, and a ten-minute monitor does not keep asserting UP for half an hour after evaluation stopped.
Silence is never health. A monitor that stops being evaluated does not keep reporting whatever it last said; it becomes UNKNOWN.
What produces UNKNOWN
UNKNOWN is not one specific failure — it is what several different situations all reduce to:
- Not enough votes on either side to reach quorum, and no disagreement to call DEGRADED instead (see Consensus's worked example).
- A stored consensus that has gone stale under the freshness rule above.
- A monitor that has not yet been evaluated at all.
Losing an assigned node is not, on its own, a rule that produces UNKNOWN. A monitor can lose a replica and become under-replicated while remaining fully quorum-capable — its remaining nodes' votes are still enough to reach a conclusive UP or DOWN. UNKNOWN follows specifically from insufficient fresh evidence for consensus, which under-replication makes more likely but does not by itself cause. See Coverage for the distinction between coverage conditions and consensus states.
Moving between states
A state change in the monitor's evidence does not, by itself, open or recover an incident. That is a separate, deliberately slower judgment — see Incidents for how a run of consistent evidence, not a single observation, confirms a state change.
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.