When a Failure Becomes an Outage
The key question in Uptime Kuma is not whether a check failed once, but when that failure should become an outage signal. Its retry and state rules give the reader a way to interpret PENDING, DOWN, UP, and MAINTENANCE, predict when an event will demand attention, and separate an unexpected target failure from a planned or differently derived result.
A monitor is making a decision under incomplete information. The target may be down, the network path may be unreliable, or the first attempt may have encountered a transient error. If Uptime Kuma alerted on every failed attempt, the system would turn uncertainty into noise. If it waited too long to declare an outage, it would make the signal less useful. The state machine is where that trade-off becomes explicit.
A failed attempt is not yet a declared outage
Uptime Kuma uses four monitor states: UP, DOWN, PENDING, and MAINTENANCE. The first two are familiar outcomes. PENDING means that the monitor has evidence of a problem but still has retries available. MAINTENANCE means that the monitor is being treated as intentionally unavailable or unprobed because of planned context. They are not interchangeable labels for a gray area; each one leads to different behavior elsewhere in the system.
Consider a monitor that was previously up. Its next request fails. If no retries are configured, the new heartbeat can become DOWN immediately. If retries remain, Uptime Kuma records the attempt as PENDING, increments the retry count, and tries again according to the retry interval. A second failure can remain pending while the retry budget is not exhausted. Once the allowed attempts have been used, the state becomes DOWN. A successful check resets the retry count and returns the monitor to UP.
The same basic sequence applies to many monitor types even though the underlying failure differs. An HTTP assertion may reject a status or content value. A DNS resolver may fail or return an unexpected record. A browser may be unavailable. A Docker daemon may not report the state of a container. The type-specific implementation supplies the error; the common monitor loop decides whether the error is still provisional or has crossed the outage threshold.
This makes the retry count an evidence policy, not a cosmetic setting. A short interval with several retries can detect a persistent failure quickly while filtering an isolated error. A long retry interval can reduce pressure on a fragile target but prolong uncertainty. A check that takes most of its interval to complete has less practical room for retries than its nominal configuration suggests. The right setting depends on the service's tolerance for delayed detection, the cost of an extra probe, and the likelihood that the probe path itself is unstable.
The transition history matters as much as the current result. Uptime Kuma marks every heartbeat with an important flag, but it does not treat every event as equally worthy of attention. The first observation is important because the system needs to establish an initial state. A meaningful change such as UP to DOWN, PENDING to DOWN, or DOWN to UP is important. Repeated UP results and repeated DOWN results still provide diagnostic history, but they do not represent a new state transition.
This separation serves two readers at once. The dashboard can receive every heartbeat and show the detailed sequence of messages, times, response durations, and retry counts. The operator can inspect how a failure developed instead of seeing only a red tile. At the same time, the event list and notification system can focus on transitions that change the operational situation. A service that remains down for an hour does not need a new alert for every ordinary check unless the operator deliberately configures resends.
Notifications apply a narrower policy than the general important-event flag. An outage transition, recovery, or a first observed state can trigger a notification. Some transitions involving maintenance update the system without being treated as an ordinary incident. If a monitor stays down, a resend interval can count down checks and send a reminder after the configured number. When the service recovers, Uptime Kuma can look up the last important down heartbeat and include the relevant time in the recovery payload. That makes the notification more useful than a bare “up” message, while still depending on the history that the system retained.
The distinction can be summarized as three different questions:
- What happened on this attempt? Every heartbeat contributes to the event history.
- Has the monitor's state changed in a meaningful way? The important flag records selected transitions.
- Should someone or something be notified now? Notification rules apply an even narrower policy, with resends and maintenance exceptions.
Conflating these questions causes predictable mistakes. If only important events were retained, an operator could lose the sequence needed to diagnose a flaky target. If every heartbeat generated an alert, the signal would become unusable. If PENDING were displayed as if it were a confirmed outage, a reader might respond before the retry policy had finished. Uptime Kuma keeps the states and the attention policy separate so that the same check can be both visible and not yet actionable.
The diagram is intentionally a model of policy, not a claim that every state transition is generated by the same event. A maintenance window is not a failed request, and a push monitor does not discover failure through the same direction of traffic as an HTTP monitor. The value of the common state vocabulary is that these different paths can still be represented and consumed consistently.
Context can change the meaning of failure
Retries are only one way Uptime Kuma avoids overreading an observation. Context can change whether a target should be checked at all and how a result should be attributed.
Maintenance is a state with a reason. A maintenance record can be manual, a single scheduled window, a cron schedule, or a recurring schedule. It stores timing and timezone information, keeps a running job in the server process, and is loaded again when the application starts. When a monitor is under maintenance, the normal check path creates a MAINTENANCE heartbeat instead of querying the target. The event remains visible as planned context rather than being silently discarded or misreported as a service outage.
This distinction is operationally important. Suppose a deployment team schedules a database migration for a period when the application will be unavailable. A failed request during that window would not tell the same story as an unscheduled failure. By making maintenance explicit, Uptime Kuma can update the dashboard and public status information while suppressing some of the notifications that would otherwise be sent for an unexpected transition. The planned state can also be attached to a status page, where readers need an explanation and time range rather than a mysterious green or red result.
Maintenance can be recurring and timezone-aware, which is useful for systems that have a regular change window. It also has a limitation: the schedule is executed by the monitoring server's process and clock. A persisted schedule is durable intent, but its live job must be running in the process, and the interpretation of local time depends on the configured timezone. If the server is stopped or its clock is wrong, the operator must verify how the window is represented after restart rather than assuming that a calendar entry alone performed the work.
Maintenance context can flow through a monitor hierarchy. Uptime Kuma allows monitors to be organized under group monitors. A child can inherit the fact that an ancestor is inactive or under maintenance, so a parent-level decision can change how descendants are treated. This is convenient for a service composed of several checks, but it also means that a child result cannot always be interpreted in isolation. The child may have a perfectly good last heartbeat while the current effective state is constrained by its parent.
Groups derive evidence from other heartbeats. A group monitor does not independently query the target represented by each child. It reads the children’s most recent heartbeats and derives a worst-case status. Inactive children are ignored. A child with no heartbeat makes the group pending. A down child makes the group down; pending children keep the group pending unless a down child is already present. If all active children are up, the group reports that all children are running.
This is a composite signal. It is useful for answering, “Is every active component in this service group currently acceptable?” It is not a second independent measurement of the children. A group can be pending because a child has not produced its first result, or because one child is still in its own retry sequence. The group therefore carries uncertainty upward. It also reuses the common retry and notification flow, so a derived failure can receive the same attention policy as a direct check.
Push monitors move the observation boundary. With an ordinary monitor, Uptime Kuma initiates a request and interprets the response. With a push monitor, an external job reports to Uptime Kuma, and the monitor judges whether a heartbeat arrived within the expected interval. This is a better fit for a backup, batch import, or scheduled script whose own process knows whether its work completed.
The state vocabulary is the same, but the failure paths change. A missing push can mean that the job failed, the scheduler did not run, the job could not reach Uptime Kuma, or the monitoring server could not receive the request. The monitor is measuring timely reporting, not independently verifying the job's downstream effects. An explicitly reported down status can bypass the usual retry path, because the caller has made a direct assertion that the operator may want to honor immediately. Silence remains a different kind of evidence from an explicit down report.
Upside-down checks invert the expected interpretation. Uptime Kuma supports a mode in which an ordinary up result is treated as down and an ordinary down result is treated as up. This is useful for a monitor whose desired condition is that something remain absent or unreachable. The mechanism is simple, but the consequence is easy to miss: notification, important-event, and uptime behavior follows the resulting status, not the intuitive meaning of the underlying probe. The monitor's name and description must make the inversion clear to anyone interpreting its history.
These cases show why a red result does not have one universal cause. It may be a direct target failure after retries, a child-derived group failure, a late push report, a deliberately inverted condition, or a maintenance boundary ending with an unsuccessful check. The common heartbeat makes the outcomes visible; it does not remove the need to inspect how the outcome was produced.
Tune sensitivity without manufacturing certainty
A useful configuration starts with the cost of each mistake. If a missed outage is expensive, the operator may prefer a fast check and a small retry budget, then add a second monitor or a second vantage point for confirmation. If a false alarm is more damaging, a longer retry policy may be appropriate, provided that the delay is acceptable. Neither choice is universally correct because the uncertainty may belong to the target, the network, the resolver, the browser, the push caller, or the monitoring process itself.
Retries should not be used to hide a badly chosen assertion. If a page returns an accepted status while the application is unusable, repeating the same shallow HTTP request only confirms the shallow condition more often. If a DNS monitor uses an unreliable resolver, more retries may produce more resolver traffic without clarifying the target's actual state. If a push job reports success before its downstream work is durable, the monitor can be perfectly consistent while the business operation still fails. Tuning comes after choosing an observation that matches the failure hypothesis.
Maintenance should also be treated as a part of the operating process, not a permanent escape hatch. A window that is too broad can turn genuine failures into planned status. A missing window can create noisy alerts during every expected deployment. The useful boundary is whether the planned context is specific, time-limited, visible to the people who need it, and reviewed when the underlying change process evolves.
Finally, an operator should distinguish confidence in classification from confidence in the world. After retries, Uptime Kuma may have high confidence that the configured check failed repeatedly. That is stronger than one isolated error. It is still not proof that every user, region, or dependency is down. A remote probe can add another perspective; a content or JSON assertion can test a deeper condition; a group can combine component states; and a push monitor can bring knowledge from the job itself. Each addition can improve the signal while adding cost and another failure surface.
The important result is not that Uptime Kuma has found a perfect threshold. It has made the threshold and its context visible. The next step is to see how these classified heartbeats become historical evidence—how the system counts them, averages them, retains them, and turns them into an uptime number that may answer a different question from the event that produced it.