monitor.burn-rate

export function burnRate(targetBasisPoints: number, totalEvents: number, badEvents: number): number

import { burnRate } from "#fune/monitor.burn-rate@^1";

/**
 * How fast an SLO's error budget is burning, in thousandths: the window's
 * error rate divided by the error rate the SLO allows. 1000 spends exactly
 * the budget over the SLO period; 14400 (14.4x) spends 2% of a 30-day budget
 * in one hour.
 *
 * Exact BigInt arithmetic: bad x 10000 x 1000 passes 2^53 at under a billion
 * bad events.
 */
export function burnRate(targetBasisPoints: number, totalEvents: number, badEvents: number): number {
  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}`);
  // An empty window has no error rate; 0 keeps an alert quiet rather than failing it.
  if (totalEvents === 0) return 0;
  const n = BigInt(badEvents) * 10000n * 1000n;
  const d = BigInt(totalEvents) * BigInt(10000 - targetBasisPoints);
  return Number((2n * n + d) / (2n * d));
}

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.burn-rate

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

The whole function, every language, is one file too: monitor.burn-rate-1.0.0.fune, 10,928 bytes, sha256 46c18382d46a5017709173ffb79dffb5064f4708ea3cbc5a92acd65d672b4ccc. It installs into a project of any language.

// fune: before monitor.burn-rate

// fune: after monitor.burn-rate

// fune: step monitor.burn-rate after <n|label>

More from the author

At 1x the budget lasts exactly the SLO period (30 days in the workbook); at 14.4x a 30-day budget is gone in 50 hours, and one hour at that rate spends 2% of it (14.4 x 1h / 720h). Budget spent in a window = burn x window / period.

Burn rate is what SLO alerts compare against a threshold: see `monitor.burn-rate-alert` for the workbook's multiwindow, multi-burn-rate rules. On its own it is the number for a dashboard ("burning at 3.2x").

## Decisions

- **Thousandths, half up.** 14.4x is `14400`. Integers keep the three languages identical. An alert that must not fire early on rounding should compare exactly, as `monitor.burn-rate-alert` does. - **An empty window is 0**, not an error: no traffic spends no budget, and a quiet night should not break the alerting. - **Exact arithmetic.** bad x 10000 x 1000 passes 2^53 below a billion bad events, so the division is exact (BigInt in TypeScript, i128 in Rust, Python's integers). The design pinned `math.round-div`; it is not used, because its integers stop at 2^53. - **It works on seconds too**: total = window seconds, bad = down seconds.

## 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, chapter 5 "Alerting on SLOs", section "Alert on Burn Rate" (https://sre.google/workbook/alerting-on-slos/): burn rate is how fast, relative to the SLO, the service consumes the error budget; 1 consumes all of it in the 30-day window; Table 5-8 uses 14.4, 6 and 1.

Files