monitor.uptime

export function uptime(checks: readonly Check[], from: number, to: number, maxGapSeconds: number): UptimeReport

/** Seconds in each state over the window, the uptime and the check counts; the four seconds add up to to - from. */
export interface UptimeReport {
  readonly upSeconds: number;
  readonly degradedSeconds: number;
  readonly downSeconds: number;
  /** not covered by any check within maxGapSeconds */
  readonly unknownSeconds: number;
  /** (up + degraded) / known time, floored; null when nothing is known */
  readonly uptimeBasisPoints: number | null;
  /** checks with from <= at < to */
  readonly checks: number;
  /** of those, the down ones */
  readonly downChecks: number;
}

import { uptime } from "#fune/monitor.uptime@^1";

import { type Check } from "./monitor_check_status.ts";  ← from monitor.check-status ^1.0.0 · built alongside by fune
import { type UptimeReport } from "./monitor_uptime_types.ts";

/**
 * 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 maxGapSeconds: a
 * monitor that stopped reporting has not proved the target was up.
 */
export function uptime(checks: readonly Check[], from: number, to: number, maxGapSeconds: number): UptimeReport {
  if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to)) throw new RangeError("from and to must be whole seconds");
  if (from > to) throw new RangeError(`from must not be after to: ${from} > ${to}`);
  if (!Number.isSafeInteger(maxGapSeconds) || maxGapSeconds < 1) {
    throw new RangeError(`maxGapSeconds must be a whole number of at least 1, received ${maxGapSeconds}`);
  }
  let up = 0;
  let degraded = 0;
  let down = 0;
  let count = 0;
  let downCount = 0;
  for (let i = 0; i < checks.length; i++) {
    const c = checks[i];
    if (c.status !== "up" && c.status !== "degraded" && c.status !== "down") {
      throw new RangeError(`unknown check status: ${String(c.status)}`);
    }
    if (i > 0 && c.at <= checks[i - 1].at) {
      throw new RangeError(`checks must be in strictly ascending time order: ${c.at} follows ${checks[i - 1].at}`);
    }
    if (c.at >= from && c.at < to) {
      count += 1;
      if (c.status === "down") downCount += 1;
    }
    // The span this check vouches for, clipped to the window.
    let end = c.at + maxGapSeconds;
    if (i + 1 < checks.length && checks[i + 1].at < end) end = checks[i + 1].at;
    const s = Math.max(c.at, from);
    const e = Math.min(end, to);
    if (e > s) {
      if (c.status === "up") up += e - s;
      else if (c.status === "degraded") degraded += e - s;
      else down += e - s;
    }
  }
  const known = up + degraded + down;
  // Floored in BigInt: never 100.00% while a down second exists, and exact
  // for windows whose seconds times 10000 pass 2^53.
  const uptimeBasisPoints = known === 0 ? null : Number((BigInt(up + degraded) * 10000n) / BigInt(known));
  return {
    upSeconds: up,
    degradedSeconds: degraded,
    downSeconds: down,
    unknownSeconds: to - from - known,
    uptimeBasisPoints,
    checks: count,
    downChecks: downCount,
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the TypeScript 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 TypeScript implementation. Install it without the registry with fune add ./monitor.uptime-1.0.0-typescript.fune, or fetch it from a terminal with fune pull monitor.uptime@1.0.0:typescript.

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