monitor.error-budget

export function errorBudget(targetBasisPoints: number, totalEvents: number, badEvents: number): ErrorBudget

/** The budget in events and in basis points of itself. */
export interface ErrorBudget {
  /** floor(total x (10000 - target) / 10000) */
  readonly allowedBad: number;
  /** allowedBad - bad; negative once over budget */
  readonly remainingBad: number;
  /** bad as a share of the exact budget, half-up; over 10000 once over budget */
  readonly consumedBasisPoints: number;
  /** 10000 - consumedBasisPoints; may be negative */
  readonly remainingBasisPoints: number;
  /** bad is strictly more than the exact budget */
  readonly exhausted: boolean;
}

import { errorBudget } from "#fune/monitor.error-budget@^1";

import { type ErrorBudget } from "./monitor_error_budget_types.ts";

function checkCounts(targetBasisPoints: number, totalEvents: number, badEvents: number): void {
  if (!Number.isSafeInteger(targetBasisPoints) || targetBasisPoints < 1 || targetBasisPoints > 9999) {
    throw new RangeError(`targetBasisPoints must be a whole number from 1 to 9999 (10000 leaves no error budget), received ${targetBasisPoints}`);
  }
  if (!Number.isSafeInteger(totalEvents) || totalEvents < 0) {
    throw new RangeError(`totalEvents must be a whole number of at least 0, received ${totalEvents}`);
  }
  if (!Number.isSafeInteger(badEvents) || badEvents < 0) {
    throw new RangeError(`badEvents must be a whole number of at least 0, received ${badEvents}`);
  }
  if (badEvents > totalEvents) throw new RangeError(`badEvents must not exceed totalEvents: ${badEvents} > ${totalEvents}`);
}

// Non-negative operands only, so half-up needs no sign handling.
function halfUp(n: bigint, d: bigint): bigint {
  return (2n * n + d) / (2n * d);
}

/**
 * The error budget of an SLO over one window: how many bad events it allows,
 * how many are left, and how much of it is spent.
 *
 * All arithmetic is exact (BigInt): a month of requests times 10000 x 10000
 * passes 2^53 long before the counts look large.
 */
export function errorBudget(targetBasisPoints: number, totalEvents: number, badEvents: number): ErrorBudget {
  checkCounts(targetBasisPoints, totalEvents, badEvents);
  const total = BigInt(totalEvents);
  const bad = BigInt(badEvents);
  // The exact budget is budgetTimes10000 / 10000 events; keep it as a fraction.
  const budgetTimes10000 = total * BigInt(10000 - targetBasisPoints);
  const allowedBad = Number(budgetTimes10000 / 10000n);
  const consumed = total === 0n ? 0 : Number(halfUp(bad * 10000n * 10000n, budgetTimes10000));
  return {
    allowedBad,
    remainingBad: allowedBad - badEvents,
    consumedBasisPoints: consumed,
    remainingBasisPoints: 10000 - consumed,
    exhausted: bad * 10000n > budgetTimes10000,
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, 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.error-budget

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

The whole function, every language, is one file too: monitor.error-budget-1.0.0.fune, 16,523 bytes, sha256 0895adf982e895f32250a3b40eac437e9a220efbad181a65b878c3c16c09fc1b. It installs into a project of any language.

// fune: before monitor.error-budget

// fune: after monitor.error-budget

// fune: step monitor.error-budget after <n|label>

More from the author

It works for request-based SLOs (total requests, failed requests) and for time-based ones (seconds in the window, seconds down). 99.9% over 30 days is 2,592,000 seconds with a budget of **2592 seconds, 43m 12s**. The `checks`, `downChecks` and `downSeconds` from `monitor.uptime` are the counts to pass.

## The numbers

- `allowedBad` = floor(total x (10000 - target) / 10000): whole events, so it floors. A budget of 1.5 events allows 1. - `consumedBasisPoints` = bad / exact budget, in basis points, rounded half up. It is measured against the *exact* budget, not the floored one, so 1 bad event out of a 1.5-event budget is 6667 (66.67%), not 10000. It exceeds 10000 once the budget is overspent; every request failing at 99.9% is 10,000,000 (1000x). - `remainingBad` = allowedBad - bad and `remainingBasisPoints` = 10000 - consumed. Both go negative when over budget, which is how far over. - `exhausted` is exact: bad x 10000 > total x (10000 - target). Exactly at budget is fully spent (`consumed` 10000, `remaining` 0) but not exhausted; one more bad event is: overspent, the point where an error budget policy usually freezes releases. - No events yet (`total` 0) spends nothing: consumed 0, not exhausted.

The design pinned `math.round-div` for the rounding; it is not used, because bad x 10000 x 10000 passes 2^53 (the limit of `round-div`'s integers) at only 90 million bad events. The division is done exactly instead, with BigInt in TypeScript, i128 in Rust and Python's own integers.

## Errors

- `targetBasisPoints must be a whole number from 1 to 9999 (10000 leaves no error budget), received X` - `totalEvents must be a whole number of at least 0, received X` - `badEvents must be a whole number of at least 0, received X` - `badEvents must not exceed totalEvents: B > T`

## Sources

- Google SRE Workbook, "Implementing SLOs" and "Alerting on SLOs" (https://sre.google/workbook/alerting-on-slos/): error budget = 1 - SLO, measured over a 30-day window. - Google SRE Book, "Embracing Risk", error budgets (https://sre.google/sre-book/embracing-risk/).

Files