Chapter 03
Roll out gradually
A rollout lets people in a few at a time, so a bug reaches 5% of your users instead of all of them. Rollouts answer three questions: who is eligible, what signal are you watching, and what would make you raise the percentage or roll back.
The rollout ladder
A typical ladder for new-checkout:
| Step | Who's eligible | Watch | Raise when | Roll back when |
|---|---|---|---|---|
| Team | email ends with @yourcompany.com | Your own use in production | The team used it for real work and found no blockers | Anything a customer would notice |
| 5% | A small share of everyone else | Errors, replays, latency, and checkout conversion for people with the flag | Every check in the list below passes over a day of normal traffic | Any check in the list fails |
| 25% | A bigger share | The same, plus load on the services checkout calls | The same | The same, or latency climbs |
| 100% | Everyone | The same | Nothing left to watch: schedule the cleanup | The same |
Who is eligible
Each flag has one or more release conditions Fig. 1. A condition set matches when every property filter passes and the person falls inside its rollout percentage, and a person who matches any set gets the flag.
Specify users for flag release. Condition sets are evaluated top to bottom - the first matching set is used. A condition matches when all property filters pass AND the target falls within the rollout percentage.
At PostHog, a flag often starts with only the engineer who made the change. Next comes the team, by email domain: email ends with @yourcompany.com. Use ends with, not contains, because contains also matches lookalike domains.
Then add a set for everyone at a small percentage, as low as 0.01%. Raising the percentage moves the cut-off and changes nobody's hash, so everyone who had the flag keeps it while new people join.
To narrow who's eligible, target a cohort (your beta testers), a person property (their plan), a country if GeoIP is on, or a whole company with group analytics. Target the data where it lives. If your server knows the plan, evaluate on the server and pass the plan in. If the plan lives in Stripe, sync it in as a warehouse property and target it like any other property.
What to watch
You should have clear rules on when to increase or decrease rollout. Watch the signals the change could break: new errors, replays of people who have the flag, and the one metric the change is meant to move. Compare people with the flag to people without it, so a bad day for everyone doesn't read as a bad rollout.
When to raise or roll back
Before you raise a percentage step, and before you see the numbers, write down your rules. Raise a percentage step only when all of these are true for people with the flag, compared to people without it, over at least a day of normal traffic:
- The error rate is not higher.
- Error tracking shows no new issue that only people with the flag hit.
- The metric the change should move, like checkout conversion, is flat or up.
- Latency on the services the change calls is flat.
- Support has no new tickets about the change.
If one of them fails, roll back by lowering the percentage or switching the flag off. Then report the blast radius: how many people had the flag while it was broken, and what they hit. The $feature_flag_called events show who got the flag.
If you already know the next step and its date, schedule the flag change and let PostHog make it.