monitor.error-budget

def error_budget(target_basis_points: int, total_events: int, bad_events: int) -> ErrorBudget

@dataclass(frozen=True)
class ErrorBudget:
    """The budget in events and in basis points of itself."""

    #: floor(total x (10000 - target) / 10000)
    allowed_bad: int
    #: allowedBad - bad; negative once over budget
    remaining_bad: int
    #: bad as a share of the exact budget, half-up; over 10000 once over budget
    consumed_basis_points: int
    #: 10000 - consumedBasisPoints; may be negative
    remaining_basis_points: int
    #: bad is strictly more than the exact budget
    exhausted: bool

from fune.monitor.error_budget import error_budget  # monitor.error-budget@^1

from .monitor_error_budget_types import ErrorBudget


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


def _check_counts(target_basis_points: int, total_events: int, bad_events: int) -> None:
    if not _whole(target_basis_points) or target_basis_points < 1 or target_basis_points > 9999:
        raise ValueError("targetBasisPoints must be a whole number from 1 to 9999 (10000 leaves no error budget), received %s" % (target_basis_points,))
    if not _whole(total_events) or total_events < 0:
        raise ValueError("totalEvents must be a whole number of at least 0, received %s" % (total_events,))
    if not _whole(bad_events) or bad_events < 0:
        raise ValueError("badEvents must be a whole number of at least 0, received %s" % (bad_events,))
    if bad_events > total_events:
        raise ValueError("badEvents must not exceed totalEvents: %d > %d" % (bad_events, total_events))


def _half_up(n: int, d: int) -> int:
    # Non-negative operands only, so half-up needs no sign handling.
    return (2 * n + d) // (2 * d)


def error_budget(target_basis_points: int, total_events: int, bad_events: int) -> ErrorBudget:
    """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. Exact integers
    throughout."""
    _check_counts(target_basis_points, total_events, bad_events)
    # The exact budget is budget_times_10000 / 10000 events; keep it as a fraction.
    budget_times_10000 = total_events * (10000 - target_basis_points)
    allowed_bad = budget_times_10000 // 10000
    consumed = 0 if total_events == 0 else _half_up(bad_events * 10000 * 10000, budget_times_10000)
    return ErrorBudget(
        allowed_bad=allowed_bad,
        remaining_bad=allowed_bad - bad_events,
        consumed_basis_points=consumed,
        remaining_basis_points=10000 - consumed,
        exhausted=bad_events * 10000 > budget_times_10000,
    )

Install

fune build

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

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

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