monitor.uptime

def uptime(checks: Sequence[Check], from_: int, to: int, max_gap_seconds: int) -> UptimeReport

@dataclass(frozen=True)
class UptimeReport:
    """Seconds in each state over the window, the uptime and the check counts; the four seconds add up to to - from."""

    up_seconds: int
    degraded_seconds: int
    down_seconds: int
    #: not covered by any check within maxGapSeconds
    unknown_seconds: int
    #: (up + degraded) / known time, floored; null when nothing is known
    uptime_basis_points: Optional[int]
    #: checks with from <= at < to
    checks: int
    #: of those, the down ones
    down_checks: int

from fune.monitor.uptime import uptime  # monitor.uptime@^1

from typing import Optional, Sequence

from .monitor_check_status import Check  ← from monitor.check-status ^1.0.0 · built alongside by fune
from .monitor_uptime_types import UptimeReport


def _whole(value: object) -> bool:
    return isinstance(value, int) and not isinstance(value, bool)


def uptime(checks: Sequence[Check], from_: int, to: int, max_gap_seconds: int) -> UptimeReport:
    """Seconds up, degraded, down and unknown over [from, to). Each check's
    status holds from its `at` until the next check, but for at most
    max_gap_seconds: a monitor that stopped reporting has not proved the
    target was up."""
    if not _whole(from_) or not _whole(to):
        raise ValueError("from and to must be whole seconds")
    if from_ > to:
        raise ValueError("from must not be after to: %d > %d" % (from_, to))
    if not _whole(max_gap_seconds) or max_gap_seconds < 1:
        raise ValueError("maxGapSeconds must be a whole number of at least 1, received %s" % (max_gap_seconds,))
    up = degraded = down = 0
    count = down_count = 0
    for i, c in enumerate(checks):
        if c.status not in ("up", "degraded", "down"):
            raise ValueError("unknown check status: %s" % (c.status,))
        if i > 0 and c.at <= checks[i - 1].at:
            raise ValueError("checks must be in strictly ascending time order: %d follows %d" % (c.at, checks[i - 1].at))
        if from_ <= c.at < to:
            count += 1
            if c.status == "down":
                down_count += 1
        # The span this check vouches for, clipped to the window.
        end = c.at + max_gap_seconds
        if i + 1 < len(checks) and checks[i + 1].at < end:
            end = checks[i + 1].at
        s = max(c.at, from_)
        e = min(end, to)
        if e > s:
            if c.status == "up":
                up += e - s
            elif c.status == "degraded":
                degraded += e - s
            else:
                down += e - s
    known = up + degraded + down
    # Floored: never 100.00% while a down second exists.
    bp: Optional[int] = None if known == 0 else (up + degraded) * 10000 // known
    return UptimeReport(
        up_seconds=up,
        degraded_seconds=degraded,
        down_seconds=down,
        unknown_seconds=to - from_ - known,
        uptime_basis_points=bp,
        checks=count,
        down_checks=down_count,
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add monitor.uptime

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./monitor.uptime-1.0.0-python.fune, or fetch it from a terminal with fune pull monitor.uptime@1.0.0:python.

The whole function, every language, is one file too: monitor.uptime-1.0.0.fune, 19,320 bytes, sha256 915fa80bdd33c7db5b73f1a098649af886ed65ae0cf1e4c06518d7c974a4e134. It installs into a project of any language.

# fune: before monitor.uptime

# fune: after monitor.uptime

# fune: replace monitor.check-status in monitor.uptime

# fune: step monitor.uptime after <n|label>

More from the author

Each check's status holds from its `at` until the next check, but for at most `maxGapSeconds`. Whatever is left of a longer gap is **unknown**: a monitor that stopped reporting has not proved the target was up. Set `maxGapSeconds` to a little more than the check interval (two intervals is common).

- The latest check before `from` carries into the window, with the same cap, so a window does not start with a hole just because no check landed exactly on its first second. It is not counted in `checks`. - Time before any check is unknown. - The window is half-open, `from <= t < to`; a check exactly at `to` belongs to the next window. - `upSeconds + degradedSeconds + downSeconds + unknownSeconds` is always `to - from`.

## The uptime figure

`uptimeBasisPoints = floor((up + degraded) * 10000 / (up + degraded + down))`.

- Degraded counts as up: the target was serving, slowly. - Unknown time is left out of both sides rather than guessed. - Floored, so it never reads 100.00% while any second was down (99,999 up seconds and 1 down second is 9999, not 10000). - `null` when nothing in the window is known. - Computed exactly (BigInt in TypeScript, i128 in Rust), so long windows do not lose precision past 2^53.

`checks` and `downChecks` are the event counts an event-based SLO wants (`monitor.error-budget`, `monitor.burn-rate`); the seconds are the time-based view.

## Errors

- `from and to must be whole seconds` - `from must not be after to: A > B` - `maxGapSeconds must be a whole number of at least 1, received X` - `checks must be in strictly ascending time order: A follows B` (checked over the whole list, not just the window) - `unknown check status: X`

Files