monitor.burn-rate-alert

export function burnRateAlert(targetBasisPoints: number, windows: readonly WindowCount[], rules: readonly BurnRule[] | null, minEvents: number | null): BurnAlert

/** Events seen over the last windowSeconds. */
export interface WindowCount {
  /** at least 1 */
  readonly windowSeconds: number;
  readonly totalEvents: number;
  readonly badEvents: number;
}

/** Fire when both windows burn at or above the threshold. */
export interface BurnRule {
  /** e.g. page or ticket */
  readonly severity: string;
  readonly longWindowSeconds: number;
  /** at most longWindowSeconds; the workbook uses 1/12 of it */
  readonly shortWindowSeconds: number;
  /** threshold, thousandths: 14400 = 14.4x */
  readonly burnRateMilli: number;
}

/** One rule, its threshold and both burn rates. */
export interface BurnRuleResult {
  readonly severity: string;
  readonly longWindowSeconds: number;
  readonly shortWindowSeconds: number;
  readonly thresholdMilli: number;
  /** half-up; firing compares exactly, not this rounded value */
  readonly longBurnMilli: number;
  readonly shortBurnMilli: number;
  /** the long window saw at least minEvents events; true when there is no minimum */
  readonly enoughEvents: boolean;
  readonly firing: boolean;
}

/** Whether anything fires, the first firing rule's severity, and every rule. */
export interface BurnAlert {
  readonly firing: boolean;
  /** the first firing rule in rule order; null when none fires */
  readonly severity: string | null;
  /** in rule order */
  readonly rules: readonly BurnRuleResult[];
}

import { burnRateAlert } from "#fune/monitor.burn-rate-alert@^2";

import { burnRate } from "./monitor_burn_rate.ts";  ← from monitor.burn-rate ^1.0.0 · built alongside by fune
import { SRE_WORKBOOK } from "./monitor_burn_rate_alert_data.ts";  ← this capability’s own data, compiled from data/sre-workbook.json into the same file by fune build
import { type BurnAlert, type BurnRule, type BurnRuleResult, type WindowCount } from "./monitor_burn_rate_alert_types.ts";

function whole(value: number): boolean {
  return Number.isSafeInteger(value);
}

// bad/total >= threshold/1000 x (10000 - target)/10000, cross-multiplied so a
// burn of 14.3995x never fires a 14.4x rule by rounding up.
function atOrAbove(w: WindowCount, thresholdMilli: number, targetBasisPoints: number): boolean {
  if (w.totalEvents === 0) return false;
  return BigInt(w.badEvents) * 10000000n >= BigInt(thresholdMilli) * BigInt(w.totalEvents) * BigInt(10000 - targetBasisPoints);
}

/**
 * Multiwindow, multi-burn-rate SLO alerting, as the Google SRE workbook
 * recommends: a rule fires only when both its long window (enough budget
 * spent to matter) and its short window (still happening now) burn at or
 * above its threshold. With rules null it uses the workbook's Table 5-8.
 *
 * minEvents guards small samples: a rule whose long window saw fewer events
 * stays quiet, since 2 bad checks out of 11 is a 36x burn of a 99.5% budget
 * but proves little. The short window is not guarded: it only confirms the
 * burn is still going on.
 */
export function burnRateAlert(
  targetBasisPoints: number,
  windows: readonly WindowCount[],
  rules: readonly BurnRule[] | null,
  minEvents: number | null,
): BurnAlert {
  if (!whole(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 (minEvents !== null && (!whole(minEvents) || minEvents < 0)) {
    throw new RangeError(`minEvents must be null or a whole number of at least 0, received ${minEvents}`);
  }
  const minimum = minEvents ?? 0;
  const counts = new Map<number, { count: WindowCount; burn: number }>();
  for (const w of windows) {
    if (!whole(w.windowSeconds) || w.windowSeconds < 1) throw new RangeError(`windowSeconds must be at least 1, received ${w.windowSeconds}`);
    if (counts.has(w.windowSeconds)) throw new RangeError(`duplicate counts for a ${w.windowSeconds}-second window`);
    // burnRate checks the counts, so every window is checked, used or not.
    counts.set(w.windowSeconds, { count: w, burn: burnRate(targetBasisPoints, w.totalEvents, w.badEvents) });
  }
  const chosen: readonly BurnRule[] = rules ?? SRE_WORKBOOK.map((r) => ({
    severity: r.severity,
    longWindowSeconds: r.longWindowSeconds,
    shortWindowSeconds: r.shortWindowSeconds,
    burnRateMilli: r.burnRateMilli,
  }));
  if (chosen.length === 0) throw new RangeError("rules must not be empty; pass null for the SRE workbook rules");
  const results: BurnRuleResult[] = [];
  let severity: string | null = null;
  for (const rule of chosen) {
    if (rule.severity === "") throw new RangeError("severity must not be empty");
    if (!whole(rule.shortWindowSeconds) || rule.shortWindowSeconds < 1) {
      throw new RangeError(`shortWindowSeconds must be at least 1, received ${rule.shortWindowSeconds}`);
    }
    if (!whole(rule.longWindowSeconds) || rule.shortWindowSeconds > rule.longWindowSeconds) {
      throw new RangeError(`shortWindowSeconds must not exceed longWindowSeconds: ${rule.shortWindowSeconds} > ${rule.longWindowSeconds}`);
    }
    if (!whole(rule.burnRateMilli) || rule.burnRateMilli < 1) throw new RangeError(`burnRateMilli must be at least 1, received ${rule.burnRateMilli}`);
    const long = counts.get(rule.longWindowSeconds);
    if (long === undefined) throw new RangeError(`no counts for a ${rule.longWindowSeconds}-second window`);
    const short = counts.get(rule.shortWindowSeconds);
    if (short === undefined) throw new RangeError(`no counts for a ${rule.shortWindowSeconds}-second window`);
    const enoughEvents = long.count.totalEvents >= minimum;
    const firing = enoughEvents && atOrAbove(long.count, rule.burnRateMilli, targetBasisPoints) && atOrAbove(short.count, rule.burnRateMilli, targetBasisPoints);
    if (firing && severity === null) severity = rule.severity;
    results.push({
      severity: rule.severity,
      longWindowSeconds: rule.longWindowSeconds,
      shortWindowSeconds: rule.shortWindowSeconds,
      thresholdMilli: rule.burnRateMilli,
      longBurnMilli: long.burn,
      shortBurnMilli: short.burn,
      enoughEvents,
      firing,
    });
  }
  return { firing: severity !== null, severity, rules: results };
}

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

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

The whole function, every language, is one file too: monitor.burn-rate-alert-2.0.0.fune, 49,170 bytes, sha256 f929270cee119def2ed9395259cd3c8fa3fe53c7ab9b4d545e38f800cb445206. It installs into a project of any language.

// fune: before monitor.burn-rate-alert

// fune: after monitor.burn-rate-alert

// fune: replace monitor.burn-rate in monitor.burn-rate-alert

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

More from the author

## The default rules (rules = null)

Shipped as `data/sre-workbook.json`, from Table 5-8 of the workbook's "Alerting on SLOs" chapter, for a 30-day SLO period:

| Severity | Long window | Short window | Burn rate | Budget consumed | |----------|-------------|--------------|-----------|-----------------| | page | 1 hour | 5 minutes | 14.4 | 2% | | page | 6 hours | 30 minutes | 6 | 5% | | ticket | 3 days | 6 hours | 1 | 10% |

Budget consumed = burn rate x long window / 30 days; the short window is 1/12 of the long one, as the workbook suggests. So the windows to count are 300, 1800, 3600, 21600 and 259200 seconds. The table has no `effective` dates: it is a published recommendation, not a rule that changes in force.

## Small samples: minEvents

Burn rates are ratios, and a ratio of small counts is noise. A new target checked every 30 s has 11 checks after five minutes; if 2 of them failed, its error rate is 18%, which burns a 99.5% budget at 36x and pages under every rule in the table, though nothing much has happened. The workbook names the problem in its section on low-traffic services ("Low-Traffic Services and Error Budget Alerting"): one failure among very few requests can look like a huge burn.

`minEvents` is the usual guard: a rule fires only when its **long** window saw at least that many events. Its `enoughEvents` says whether it did. The short window is not guarded, because it is only there to prove the burn is still happening, and a 5-minute window of a target checked every 30 s never holds more than 10 checks. Since each rule has its own long window, the guard is per rule: with 90 events in the last hour and 500 in the last six, a minimum of 100 silences the 1-hour rule and leaves the 6-hour one free to page.

`null` or `0` means no minimum, which is what 1.0.0 did: every 1.0.0 vector gives the same answer here with `minEvents` null (and `enoughEvents` true).

## Changes from 1.0.0

- A fourth parameter, `minEvents: int?`. - `BurnRuleResult.enoughEvents`.

Both break a caller written for 1.0.0 (one more argument to pass, one more field in the result), hence 2.0.0 rather than 1.1.0: a project on `^1` keeps 1.0.0 until it moves to `^2`. With `minEvents` null the answers are 1.0.0's.

## Decisions

- **Firing is exact.** It compares bad x 10,000,000 against threshold x total x (10000 - target), not the rounded `longBurnMilli`: a burn of 14.3995x shows as `14400` but does not fire a 14.4x rule. - **Severity is the first firing rule in rule order.** List pages before tickets (the workbook table already does), and a fast burn that also trips the ticket rule still pages. - **An empty window (total 0) never fires.** - **Every window is checked**, including ones no rule uses: bad counts in any of them are a bug upstream. - Each rule needs counts for exactly its two window lengths, so the caller counts once per distinct length; a rule with short = long is allowed (a single-window alert). - `minEvents` guards the long window only, and counts every event in it, good or bad. - `rules` = `[]` is an error, since it is far more likely a config mistake than a wish never to alert; null means the workbook rules.

## Errors

- `targetBasisPoints must be a whole number from 1 to 9999 (10000 leaves no error budget), received X` - `minEvents must be null or a whole number of at least 0, received X` - `windowSeconds must be at least 1, received X` - `duplicate counts for a 3600-second window` - the count errors of `monitor.burn-rate` (`badEvents must not exceed totalEvents: B > T`, ...) - `rules must not be empty; pass null for the SRE workbook rules` - `severity must not be empty` - `shortWindowSeconds must be at least 1, received X` - `shortWindowSeconds must not exceed longWindowSeconds: S > L` - `burnRateMilli must be at least 1, received X` - `no counts for a 3600-second window`

## Sources

Google SRE Workbook, chapter 5 "Alerting on SLOs", the multiwindow, multi-burn-rate alerts section and Table 5-8 (https://sre.google/workbook/alerting-on-slos/): page 1h / 5m / 14.4 / 2%; page 6h / 30m / 6 / 5%; ticket 3d / 6h / 1 / 10%; "make the short window 1/12 the duration of the long window"; and the "Low-Traffic Services and Error Budget Alerting" section of the same chapter for the small-sample problem `minEvents` guards against.

Files