Percentage rollouts

Turn a flag on for a share of your users and raise it a step at a time. Every user lands in one of a hundred buckets, from their key alone, and stays there: the same answer on every server and in every SDK, with no network call.

Applies to: CLI 3.2 · Node 5 · Go 2 · Python 4
Before this: 3 · Targeting rules

4.1How a user lands in a bucket

Every flag with a rollout splits your users into 100 buckets. A user’s bucket comes from two things: the flag’s salt and the user’s key. A rollout of 25% turns the flag on for buckets 0 to 24, so a quarter of your users see it, and they are the same quarter every time.

JavaScript · the whole function

// FNV-1a, 32-bit, over "salt:key", then modulo 100.
export function bucket(salt, key) {
  let h = 0x811c9dc5;
  for (const byte of new TextEncoder().encode(`${salt}:${key}`)) {
    h ^= byte;
    h = Math.imul(h, 0x01000193) >>> 0;
  }
  return h % 100;
}

bucket('checkout-v2', 'u_4821');   // 83

So u_4821 sits in bucket 83: it gets the flag once the rollout passes 83%. The salt is the flag’s key unless you set one. Two flags with the same salt put a user in the same bucket: give two changes one salt to roll them out to the same people. The instrument on this page runs this function: try your own keys in it.

4.2Set a rollout from the CLI

Rollouts are per environment. Set one with sy rollout set; the SDKs stream the change and use it within two seconds.

Terminal

$ sy rollout set checkout-v2 --percent 25 --env production
✓ checkout-v2 · production · rollout 10% → 25%
  buckets 0–24 on · version 117 · streamed to 38 SDKs

Go in steps and watch your errors between them: 1, 5, 25, 50, 100 is the usual ladder. sy rollout watch prints what the flag answered, once a second, while you do.

Terminal

$ sy rollout watch checkout-v2 --env production
time      on/s   off/s   on %
14:32:08   412   1,236   25.0
14:32:09   398   1,207   24.8
14:32:10   421   1,252   25.2

4.3Read the flag in your code

Pass the same key everywhere: it decides the bucket. The SDK keeps the rules in memory and answers locally, in about two microseconds.

Node · @switchyard/node 5

import { Switchyard } from '@switchyard/node';

const flags = new Switchyard({
  sdkKey: process.env.SWITCHYARD_SDK_KEY,
});
await flags.ready();

// The same user key everywhere: it decides the bucket.
if (flags.isOn('checkout-v2', { key: user.id })) {
  return renderCheckoutV2(cart);
}

Go · switchyard-go 2

client, err := switchyard.New(os.Getenv("SWITCHYARD_SDK_KEY"))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// The same user key everywhere: it decides the bucket.
if client.IsOn("checkout-v2", switchyard.User{Key: user.ID}) {
  return renderCheckoutV2(cart)
}

Python · switchyard 4

from switchyard import Switchyard

flags = Switchyard(sdk_key=os.environ["SWITCHYARD_SDK_KEY"])

# The same user key everywhere: it decides the bucket.
if flags.is_on("checkout-v2", key=user.id):
    return render_checkout_v2(cart)

4.4The rollout’s fields

As they appear in sy flag get, the API and the SDKs’ rule objects.

Field	Type	Default	What it does
percent	0–100, whole	0	Buckets 0 to `percent` − 1 get the flag on.
salt	text	the flag’s key	Mixed into the hash. Changing it moves every user to a new bucket.
by	key · account · device	key	Which of the user’s attributes decides the bucket.
on · off	variation	true · false	What users inside and outside the rollout get.
schedule	up to 20 steps	none	Raises `percent` at set times, e.g. 5 at 09:00, 25 at 14:00.

4.5Before you change a rollout

Caution

Changing the salt reshuffles everyone. About half the people who had the flag lose it, and as many who did not get it. Change a salt only while the rollout is at 0% or 100%.

Check

Bucket by account when people share one. By key, two people on one team can see two different checkouts. Set by to account before the first step, not after.

Note

Lowering the percent takes the flag away at once from the buckets you drop. Users keep their bucket, so raising it again gives it back to the same people.

4.6Limits

Smallest step: 1%, one bucket
A change reaches the SDKs: under 2 s, streamed
User key: up to 64 characters
Scheduled steps a flag: 20
Evaluations: no limit: they run in your process