Percentage rollouts
Assign a stable cohort and expand a release without reshuffling subjects.
A percentage condition hashes one context attribute into a deterministic bucket. The same value keeps the same assignment while the flag, rule, attribute path, and normalized subject value stay stable.
Use percentages to expand a release predictably after narrow validation. They allocate traffic; they do not measure experimental outcomes or replace application telemetry.
Choose the identifier for the unit that must experience the release consistently.
| Desired consistency | Attribute example |
|---|---|
| One person across sessions | user.id |
| Everyone in one customer account | account.id |
| One installation or device | Stable application-owned installation ID |
| One anonymous session only | Durable session ID, when session-level movement is acceptable |
Use opaque, stable identifiers. Avoid timestamps, random values, emails, mutable display names, or values regenerated on every request.
Nested paths such as account.id are valid. Missing paths miss the percentage condition and continue
to later rules or the fallback.
A 10% rule does not enable the first ten requests. It selects buckets based on the rollout attribute. Repeated evaluations for the same subject remain in the same bucket.
Increasing from 10% to 20% retains the original cohort and admits more buckets. Decreasing removes some of the most recently included allocation while preserving deterministic assignment.
Do not promise that a percentage equals a precise user count. Hash distribution approaches the target across a sufficiently large population.
For an account-level checkout release:
account.plan equals pro and 5% by account.id.Each change should state its observation window, decision owner, and rollback condition. Pause by leaving the allocation unchanged. Roll back by reducing or removing the rule.
These changes can move subjects between buckets:
user.id to account.id.If the rollout unit must change, treat it as a new rollout. Return to a narrow cohort and validate the new assignment rather than assuming continuity.
FeatureGate provides hosted request counts, errors, rate limits, and direct per-flag totals. Local snapshot evaluations remain inside the application and are not exposure analytics.
Use application logs, metrics, traces, and business analytics to judge outcomes. Avoid logging full evaluation context, resolved values, or raw customer identifiers.
After 100% allocation, make the intended value the environment fallback. Remove the rollout rule and observe the stable state before deleting the old application branch.
Archive the temporary flag only after callers no longer depend on it. A 100% rule is not a completed cleanup; it still leaves runtime complexity and guarded code.
Related pages: Run a controlled rollout, Targeting rules, and Review and clean up flags.