Creating guarded rollouts

Overview

This topic explains how to create a guarded rollout. Guarded rollouts let you progressively increase traffic to a flag variation over time while monitoring chosen metrics for regressions. If LaunchDarkly detects a regression, it can stop the release and send you a notification.

Prerequisites

To create a guarded rollout, you should first complete the following prerequisites:

Create metrics

Before you can begin a guarded rollout, you must choose one or more existing metrics or create new metrics that you want to monitor. To learn how, read Creating and managing metrics.

Determine regression thresholds

For each metric you use in the guarded rollout, you can use the LaunchDarkly default regression threshold, or use a custom threshold:

• The Default option uses LaunchDarkly’s standard regression threshold. This option is appropriate for most guarded rollouts.
• The Set custom thresholds option lets you specify a custom threshold. This option requires familiarity with statistical analysis concepts. To learn more, read Regression thresholds for guarded rollouts.

Create a guarded rollout

You can create a guarded rollout and begin monitoring metrics:

• when you toggle the flag on and begin serving a new variation, or
• if the flag is already toggled on, when you make a change to a flag variation.

You can create a guarded rollout on any flag targeting rule, as long as there are no other guarded rollouts, progressive rollouts, or experiments running on the flag and the flag is not a migration flag.

To create a guarded rollout and begin monitoring metrics on a flag:

1. Navigate to the flag’s Targeting tab.
2. Find the flag targeting rule for which you want to create a guarded rollout and click Edit.
3. From the Serve menu select “Guarded rollout.” The guarded rollout setup options appear.
4. If the flag is a multivariate flag, choose the new Variation to roll out.
   • The new variation for boolean flags is the variation not currently being served, by default.
5. If the flag is a multivariate flag, select a Control variation that the flag can revert to in the event of a regression.
   • The control variation for boolean flags is the current variation, by default.
6. Select one or more Metrics to monitor.
7. Select a randomization unit to Target by.
8. Select a regression detection threshold of the LaunchDarkly Default, or Set custom thresholds for each metric.
9. Select a Rollout duration. LaunchDarkly automatically increases the percentage of contexts receiving the new variation over the course of the rollout duration, until the amount reaches 100%.
10. Click Review and save.

9. (Optional) Check the Automatic rollback option if you want LaunchDarkly to automatically revert your change when it detects a regression, in addition to a notification. LaunchDarkly will always roll back a release automatically if it detects a sample ratio mismatch (SRM).
10. Select a Rollout duration. LaunchDarkly automatically increases the percentage of contexts receiving the new variation over the course of the rollout duration, until the amount reaches 100%.
11. Click Review and save.

The rule displays the percentage of contexts that have been exposed to the new variation:

The top of the flag’s targeting tab also displays the status of the guarded rollout. To view more details about the guarded rollout, click on the flag’s Monitoring tab. To learn more, read Managing guarded rollouts.

If LaunchDarkly detects a regression, LaunchDarkly sends you an email, an in-app notification, and, if you have the integration configured, a Slack, Microsoft Teams, or PagerDuty notification. To learn how to set up these integrations, read Setting up Slack accounts and permissions, Setting up the Microsoft Teams integration, and PagerDuty for guarded rollouts.

Rollback behavior

If you are using a guarded rollout on a prerequisite flag and LaunchDarkly automatically rolls back the change, it will not also roll back any changes on the dependent flags. You must roll back changes on dependent flags separately.

LaunchDarkly will always automatically roll back a rollout if it detects a sample ratio mismatch (SRM). To learn more about SRMs, read Understanding sample ratios.