Gradual Rollouts
A knob can serve a new value to a percentage of entities, such as users, accounts or hosts, instead of everyone at once. Ramp up while you watch your dashboards, and roll back instantly if something looks wrong.
Start Small
Section titled “Start Small”Add rollout_pct and rollout_value to a definition to serve that value to
that percentage of hash buckets; every other caller gets default. A flag
ramps from default 0 to rollout_value 1. These examples continue in the Quick-start
shell and directory, with the publish helper defined:
publish payments:new_processor '{"default":0,"rollout_pct":10,"rollout_value":1}'Each read passes the entity’s stable identifier as the hash value:
sleep 1detent get payments:new_processor --hash user-1# 0detent get payments:new_processor --hash user-42# 1bool enabled = client.get_or_panic("payments:new_processor", user_id) == 1;The same identifier always lands in the same bucket, across reads, processes,
hosts, languages and restarts. user-42 stays enabled until you change the
knob.
How Buckets Work
Section titled “How Buckets Work”Detent hashes the knob name and the hash value together with SHA-256, takes the first eight bytes as a big-endian integer, and reduces it modulo 100:
bucket = u64_be(SHA256(knob_name || 0x00 || hash_val)[0..8]) % 100value = bucket < rollout_pct ? rollout_value : defaultThree properties fall out of that:
- Sticky. A given
(knob, hash value)pair always maps to the same bucket. - Monotonic. Raising the percentage only adds buckets, so everyone already enabled stays enabled as you ramp up.
- Independent. The knob name is part of the input, so the same user lands in unrelated cohorts for different knobs; your 10% beta testers aren’t always the same 10% of people.
0 serves rollout_value to nobody, and 100 to everybody who supplies a
hash value. The same rule ramps any integer: a batch size of 25 that 10% of
callers see as 50 is {"default":25,"rollout_pct":10,"rollout_value":50}.
Ramp Up
Section titled “Ramp Up”Publish higher percentages as you gain confidence:
publish payments:new_processor '{"default":0,"rollout_pct":50,"rollout_value":1}'# Check your dashboards before advancing.publish payments:new_processor '{"default":0,"rollout_pct":100,"rollout_value":1}'sleep 1detent get payments:new_processor --hash user-1# 1detent get payments:new_processor# 0Finish or Roll Back
Section titled “Finish or Roll Back”To finish the rollout for every caller, hashed or not, publish the knob with the new default and no rollout:
publish payments:new_processor '{"default":1}'sleep 1detent get payments:new_processor# 1To roll back everyone, publish "default": 0 without rollout_pct
instead. Because a publish replaces the whole definition, leaving out
rollout_pct and rollout_value removes the gate.
When the feature is fully launched and stable, make the new path unconditional in code, then remove the knob read, its live definition and its baked default.