From 4c4f4e54a9b252a22b633afcdd3005d3aacba88d Mon Sep 17 00:00:00 2001 From: Emiel Verkade Date: Wed, 23 Apr 2025 15:07:11 +0100 Subject: [PATCH 1/2] Add some more detail to flag allocations --- .../concepts/flag-allocations.md | 22 +++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/feature-flagging/concepts/flag-allocations.md b/docs/feature-flagging/concepts/flag-allocations.md index f637c8db..d02988a5 100644 --- a/docs/feature-flagging/concepts/flag-allocations.md +++ b/docs/feature-flagging/concepts/flag-allocations.md @@ -15,7 +15,25 @@ In Eppo, allocations are stacked in a vertical waterfall as seen below: Here, there are two allocations: -- The first allocation is a feature gate that targets internal users, which are identified with by their email domain. If a user's email matches the criteria, they are show `Variant 1`. If not, they are moved along to the next allocation (i.e down the waterfall). -- The second allocation is an experiment allocation that targets users in North America using an iPhone. 50% of users who match this criteria see `Variant 1` and the remaining 50% of users see `Variant 2`. If users do no match, they are moved along. Since there are no more allocations to evaluate, all remaining users see the default value, which in this example is `Variant 1`. +- The first allocation is a feature gate that targets internal users, which are identified with by their email domain. If a user's email matches the criteria, they are show `Variant 1`. If not, they are moved along to the next allocation (i.e down the waterfall). +- The second allocation is an experiment allocation that targets users in North America using an iPhone. 50% of users who match this criteria see `Variant 1` and the remaining 50% of users see `Variant 2`. If users do no match, they are moved along. Since there are no more allocations to evaluate, all remaining users see the default value, which in this example is `Variant 1`. Note that it is possible to reduce an allocation's traffic exposure to less than 100%. In this case, the allocation's rules are evaluated and then subsequently traffic exposure check is computed. Subjects that pass the rules test but fall outside the traffic exposure continue down the waterfall to the next rule. + +## Traffic exposure adjustments + +When you adjust the traffic exposure of an allocation: + +- **Modifying traffic exposure**: When you modify traffic exposure, existing users who were already assigned to the allocation will maintain their variant assignments when they return. This means that users who have previously been bucketed for this allocation will continue to receive the same experience. Only new users (who are being evaluated for the first time) and users who were not previously bucketed for this allocation will be subject to the updated traffic rules. + +- **Experiment completion**: This is particularly useful for experiments with a measurement window. For example, if you've reached your sample size goals, you can set traffic exposure to 0% to stop new assignments while allowing already-assigned users to complete their measurement window. + +## Overriding allocations with feature gates + +The waterfall structure of allocations allows for powerful override capabilities: + +- **Error recovery**: If you discover an issue with an experiment, you can add a feature gate above it in the waterfall targeting 100% of users to a specific variant (e.g. control). + +- **Priority of allocations**: Since allocations are evaluated from top to bottom, a feature gate placed above experiment allocations will take precedence, overriding any experiment assignments for both new and returning users. + +- **Emergency toggles**: This structure provides a quick way to implement emergency toggles to revert all users to a safe experience when needed. From d4fe96d5e4749b0878bfcf23605003b750f04431 Mon Sep 17 00:00:00 2001 From: Emiel Verkade Date: Wed, 23 Apr 2025 16:29:42 +0100 Subject: [PATCH 2/2] Update to more accurately reflect the behaviour --- docs/feature-flagging/concepts/flag-allocations.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/feature-flagging/concepts/flag-allocations.md b/docs/feature-flagging/concepts/flag-allocations.md index d02988a5..a6853847 100644 --- a/docs/feature-flagging/concepts/flag-allocations.md +++ b/docs/feature-flagging/concepts/flag-allocations.md @@ -24,7 +24,9 @@ Note that it is possible to reduce an allocation's traffic exposure to less than When you adjust the traffic exposure of an allocation: -- **Modifying traffic exposure**: When you modify traffic exposure, existing users who were already assigned to the allocation will maintain their variant assignments when they return. This means that users who have previously been bucketed for this allocation will continue to receive the same experience. Only new users (who are being evaluated for the first time) and users who were not previously bucketed for this allocation will be subject to the updated traffic rules. +- **Increasing traffic exposure**: When you increase traffic exposure, existing users who were already assigned to the allocation will maintain their variant assignments when they return (i.e. have sticky assignments). This means that users who have previously been bucketed for this allocation will continue to receive the same experience. Only new users (who are being evaluated for the first time) and users who were not previously bucketed for this allocation will be subject to the updated traffic rules. + +- **Decreasing traffic exposure**: When you decrease traffic exposure, existing users who were already assigned to a bucket will be re-evaluated. This means that users who have previously been bucketed for a specific variant will potentially receive a different experience. - **Experiment completion**: This is particularly useful for experiments with a measurement window. For example, if you've reached your sample size goals, you can set traffic exposure to 0% to stop new assignments while allowing already-assigned users to complete their measurement window.