Setting up contexts for guarded rollouts
Overview
This topic explains how to set up context kinds for use in guarded rollouts.
Guarded rollouts availability
All LaunchDarkly accounts include a limited trial of guarded rollouts. Use them to see how well the feature supports your release process in production.
Randomization units
A guarded rollout uses a single context kind, called a randomization unit, to determine how to assign traffic to flag variations.
Most guarded rollouts use the request
or user
context kind as the randomization unit. This means the rollout assigns variations based on the request or user evaluating the flag. You can also use a different context kind, such as device
or organization
, depending on how your application is configured.
Choose the randomization unit
The randomization unit must be available in both the flag and to any metrics you want to monitor.
We recommend choosing a randomization unit evaluated by a large number of unique contexts. This helps LaunchDarkly detect performance differences between variations more quickly.
Minimum context requirement for guarded rollouts
A minimum number of contexts must evaluate a new flag variation to advance to the next stage of the rollout. If this minimum sample size for guarded rollouts isn’t met, LaunchDarkly automatically rolls back the change.
Requests
For backend-only changes, the request
context kind is often the best choice. Systems typically generate many distinct requests, and backend metrics like latency and error rate are usually measured per request.
To use request
contexts, configure a context with the kind
set to "request"
and a key
that uniquely identifies the request and remains consistent throughout the request lifecycle:
Users
A user
randomization unit is often the best choice for:
- frontend-only changes
- backend changes that may affect frontend metrics
- backend changes that may impact performance outside the scope of the current request
Confirm that your user context represents a distinct user
If you use LaunchDarkly, you’re likely already using user
contexts, as this is the default context kind in most LaunchDarkly SDKs. However, make sure your user
keys uniquely identify individual users of your application. If they represent something else, like organizations or requests, your rollouts may not behave the way you expect.
To use user
contexts, configure a context with the kind
set to "user"
and a key
that uniquely identifies the user across all interactions:
If your application supports both logged-in and logged-out end users, make sure each user has a distinct key that remains consistent throughout their experience. To learn more, read Managing experiments with logged-out and logged-in end users.
Multi-contexts
To make a context kind available in your guarded rollouts, you must instrument your application code consistently. To simplify this, we recommend using multi-contexts to include multiple context kinds in each evaluation.
For example, if your application has both a frontend and a backend service:
- On the client side, set the current context to a multi-context that includes all the contexts the frontend knows about, such as
user
anddevice
. - On the server side, create a multi-context that includes all the contexts the backend knows about, such as
user
andrequest
. Use this multi-context when evaluating flags.- Use the same multi-context in any custom event tracking calls to ensure consistency with flag evaluations.
- In larger codebases, use middleware to consistently set the LaunchDarkly context for each request.
Make context kinds available in guarded rollouts
Before you can use a context kind as a randomization unit, you must mark it as Available for experiments. You must also select an industry-standard randomization unit to associate with the context kind.
The "New context kind" dialog with the Available for experiments checkbox and randomization unit mapping field called out.
After that, you can configure any metrics that apply to that context kind to use it as a randomization unit.
When creating a guarded rollout, you must choose a randomization unit supported by all the metrics you want to monitor. Only context kinds supported by the selected metrics’ randomization units are available for guarded rollouts.