Skip to content
bucker

Production assertions

Some of the costliest bugs throw nothing: a double charge, a wrong total, a skipped email. An error tracker sees exceptions and APM sees latency, so these reach the support desk first. Production assertions let your code state a rule and let Bucker count whether it held, per release.

Assertions are opt-in code you write. Nothing is collected until you add a call, and the calls never throw into the code they guard.

The three calls

import { assertAlways, assertSometimes, assertUnreachable } from '@bucker/sdk-core/assertions'

assertAlways('checkout.total', order.total === sum(order.lines), { total: order.total })
assertSometimes('cache.hit', hit)               // is it ever true?
assertUnreachable('legacy.path', { route })     // reaching this line is a violation
from bucker_sdk import assert_always, assert_sometimes, assert_unreachable

assert_always("checkout.total", order.total == sum(order.lines), {"total": order.total})

Each returns its condition unchanged, so it can sit inside an expression. The id is a short name you choose ([A-Za-z0-9][A-Za-z0-9._:/-]{0,95}); it is on the wire and in the issue's fingerprint.

What leaves the process

  • Passes are counted in process, per assertion id and minute. One assertion_counters item a minute carries ids and counts only: evaluations, violations and (for sometimes) how often it held. There is no operand, no text and no project in it; the project is the key's.
  • Only a violation sends an event. It carries the operands you passed, rendered through the state-slice projection and scrubbed at both tiers. At most five violation events leave per minute per process; the counter still counts every one.
  • With no client configured, nothing is counted and nothing is sent.

What Bucker does with it

  • A violation is an ordinary issue, fingerprinted on the assertion id, so it triages, assigns, resolves and alerts like any other. Paging on one is an ordinary alert rule.
  • Release health shows violations per million evaluations beside the crash-free rate, for always and unreachable assertions. A release that no assertion ran in has a null rate, never zero. The rate is not available with an environment filter: counters carry no environment.
  • A sometimes assertion that never held in a release is reported, flagged lowSample below 30 evaluations so a thin count is not read as a verdict.
  • Agents read the per-assertion, per-release view with the assertions_list tool (read, event:read). Its assertion ids, release labels and issue titles come from your code and are served as untrusted text.

Proposed assertions

When an issue caused by silent wrongness is resolved, the remediation lane may propose the assertion that would have caught it, in the ladder category assertion_add. The proposal is only made after it fails on the code the issue lived in and passes on the fix: an assertion that is never evaluated, held before the fix, failed for another reason, or still fails after the fix is refused with the reason. It is opened as a draft pull request; the category never goes above DRAFT_PR and Bucker never merges. You merge it, and you decide which assertions page.

Limits

Counter rows per item are bounded, per-row counts are bounded, a minute outside a window of five minutes ahead and seven days behind is discarded, and replays of the same item add their counts again (the rate is unchanged by a replay; only absolute counts drift).