Engineering1 min read

Percentage rollouts are a hashing problem

A 25% rollout is not "one request in four". It is a stable answer to "is this user in?", identical on every server, that never flips a user back out. That is a hashing problem.

Avery Lin

Avery Lin

Staff Engineer, Edge ·

Engineering cover: Percentage rollouts are a hashing problem

The naive way to roll a feature out to 25% of users is Math.random() < 0.25. It works for exactly one request. On the next, the same user has a three-in-four chance of losing the feature they just saw.

What a rollout percentage must guarantee

  1. Sticky: the same user gets the same answer on every request.
  2. Consistent: every server, in every region, agrees without talking to each other.
  3. Monotonic: raising 25% to 50% only ever adds users; nobody who had the feature loses it.

Hash, then bucket

Driftwire hashes the flag salt and the context key together, takes the result modulo 100, and calls that the user’s bucket. A 25% rollout serves buckets 0–24.

Diagram: a context key hashed with a salt into bucket 17 of 100; buckets 0 to 24 are lit for a 25% rollout
sdk/rollout.tsTypeScript
// What an edge node receives: a diff against the version it holds.
interface RulesetDiff {
    version: number
    previous: number
    changed: Record<string, FlagRules>
    removed: string[]
}

function apply(diff: RulesetDiff) {
    if (diff.previous !== store.version) return resync() // missed one: fetch a snapshot
    store.merge(diff.changed, diff.removed)
    store.version = diff.version
}

Because buckets never move, raising the percentage is monotonic for free: bucket 17 is in at 25%, at 50% and at 100%.

Why a salt per flag

Without one, the same 25% of users would be the guinea pigs for every experiment. Salting by flag reshuffles who goes first each time.

RolloutsHashingSDK
Avery Lin

Written by

Avery Lin

Staff Engineer, Edge

Avery builds the edge evaluation layer at Driftwire: the part that answers "is this flag on?" four hundred thousand times a second without asking anyone.

More posts by Avery Lin