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 monitoring a flag change, you must create the metrics 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.

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

1. On the flag rule you want to add a guarded rollout to, click + Add rollout.
2. Select Guarded rollout.
3. Select Metrics to monitor.
4. Select a randomization unit to Target by.
5. Select a regression detection threshold of the LaunchDarkly Default, or Set custom thresholds for each metric.
6. (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).
7. 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%.
8. 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.