Setting up contexts for guarded rollouts | LaunchDarkly

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.

Deciding the randomization unit

A randomization unit must be available both in the flag and in any metrics you want to monitor.

We recommend choosing a randomization unit that has a lot of unique contexts evaluating the flag, so LaunchDarkly can determine more quickly whether or not the new variation has impacted performance.

Minimum context requirement for guarded rollouts

A new flag variation must be evaluated by a minimum number of contexts to be able to progress 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, a request context kind is often the best choice because systems generate many distinct requests, and backend metrics such as latency and error rate are typically measured per request.

To use request contexts, configure a context with the kind set to "request" and a key that’s some unique value that stays consistent throughout the request:

1 {
2   "kind": "request",
3   "key": "request-key-abc-123"
4 }

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 likely already use user contexts, as this is the default context kind used in LaunchDarkly SDKs. However, be sure that your user keys represent distinct 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:

1 {
2   "kind": "user",
3   "key": "user-key-123abc",
4   "name": "Anna"
5 }

If your application supports logged-in and logged-out end users, you should ensure that every logged-in and logged-out user gets a distinct key that stays consistent throughout their experience. To learn more, read Managing experiments with logged-out and logged-in end users.

Multi-contexts

Making a context kind available in your guarded rollouts requires consistent instrumentation throughout any of your application code that uses LaunchDarkly. To make this easier, we recommend using multi-contexts to include more than one context kind 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 containing all the contexts the frontend knows about, such as user and device.
On the server side, create a multi-context containing all the contexts the backend knows about, such as user and request. Then use the multi-context as the context when evaluating flags.
- If you use custom events to track backend metrics, make sure any event tracking calls use the same multi-context as the flag evaluations.
- In larger codebases, a common approach is to create middleware for your service that sets the LaunchDarkly context for each request consistently.

Making context kinds available in guarded rollouts

Before you can use a particular context kind as a randomization unit, you must make it available.

First, when editing or creating the context kind, 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 can be measured for that context kind to use it

The "Metric definition" section of a new metric with the randomization unit called out.

When creating a guarded rollout, you must select a randomization unit that is supported by every metric you want to monitor. The available context kinds are based on the randomization units supported by the metrics you select.