Consensus
How the nodes assigned to a monitor turn their observations into one published state.
What consensus answers
A monitor is not checked once. It is checked independently by every node its assurance level assigns it to, and the monitor's published state is what that evidence supports together — not whichever probe answered last, and not a majority vote in the ordinary sense either. Consensus is the fixed rule that turns several nodes' recent observations into one state.
Votes
Each assigned node's recent observation of a monitor counts as one vote: an UP vote, a DOWN vote, or no vote at all if the node has no sufficiently recent observation to offer. Consensus is evaluated against an assurance level's quorum — the minimum number of votes needed before an answer can be conclusive — not against the full set of assigned nodes.
The rule
Given the votes gathered for a monitor and its assurance level's quorum, the published state follows one fixed rule, in this order:
- If the down-votes alone meet the quorum, the state is DOWN.
- Otherwise, if the up-votes alone meet the quorum, the state is UP.
- Otherwise, if there is at least one up-vote and at least one down-vote, the state is DEGRADED — the evidence disagrees, and neither side has enough votes on its own to settle it.
- Otherwise, the state is UNKNOWN.
A disabled monitor never reaches this rule at all: it is PAUSED, unconditionally, before any vote is counted. See States for what each of these five states means and how a monitor moves between them.
Worked example
Standard assurance asks for 3 desired replicas and a quorum of 2. A monitor evaluated against three assigned nodes' votes:
- 2 DOWN votes, 0 UP votes → DOWN (the down-votes meet the quorum).
- 2 UP votes, 1 DOWN vote → UP (the up-votes meet the quorum; the single disagreeing vote does not prevent it).
- 1 UP vote, 1 DOWN vote → DEGRADED (neither side meets the quorum alone, and both sides have evidence).
- 1 UP vote, 0 DOWN votes → UNKNOWN (neither side meets the quorum, and only one side has any evidence at all).
Assurance levels
An assurance level names two numbers: how many nodes a monitor asks to be assigned to (desired replicas), and how many votes are needed to settle a state (quorum). Pinggy has three:
| Level | Desired replicas | Quorum |
|---|---|---|
| Standard | 3 | 2 |
| Enhanced | 5 | 3 |
| High assurance | 7 | 4 |
A higher assurance level asks for more independent evidence before a state is conclusive — more nodes must agree, and more disagreement is tolerated before the state falls back to DEGRADED or UNKNOWN.
Freshness
A vote only counts if the observation behind it is recent enough. A stored consensus that is itself too old to still describe the present is reported as UNKNOWN, whatever it last said — see the freshness rule in States. Silence is never health.
What consensus is not
Consensus answers endpoint health: what the assigned nodes' probes observed. It says nothing on its own about whether enough nodes are assigned in the first place, or whether the fleet has the capacity to place them — that is monitoring coverage health, a separate question answered in Coverage. A monitor can be fully covered and DOWN, or under-replicated and still UP: the two questions are independent, and Pinggy answers them separately rather than folding one into the other.
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.