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_countersitem a minute carries ids and counts only: evaluations, violations and (forsometimes) 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
alwaysandunreachableassertions. 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
sometimesassertion that never held in a release is reported, flaggedlowSamplebelow 30 evaluations so a thin count is not read as a verdict. - Agents read the per-assertion, per-release view with the
assertions_listtool (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).