Health checks for guarded rollouts

Overview

This topic explains how to use health checks for guarded rollouts to confirm your rollout setup and troubleshoot configuration problems.

Health check statuses

When you create a guarded rollout, LaunchDarkly provides a health check status below the Target by field.

The health check statuses include:

• Health check waiting: LaunchDarkly does not have enough information yet about your guarded rollout configuration to determine its health status.
• Healthy: Your flag or AI Config is receiving evaluations, your metrics are tracking events, and your flag or AI Config and metrics are encountering the same context kinds.
• Health warnings: There is at least one problem with your guarded rollout configuration.

Hover over the status to view your rollout’s health checks:

The individual health checks are explained below.

Flag evaluations

The flag evaluation health check can have a status of:

• Flag is receiving evaluations: Contexts are encountering your flag, and your SDKs are sending flag evaluation information to LaunchDarkly.
• Flag is not receiving evaluations: Either your flag is not configured correctly in your code, or your SDK is not set up correctly.

You can expand the Evaluations graph at the top of the flag Targeting tab to view how many contexts are encountering the flag and which variation they are receiving.

Example: Flag is not receiving evaluations

Your organization creates a guarded rollout using the user context kind. After saving the configuration, the health check displays “Flag is not receiving evaluations.” This means LaunchDarkly has not yet received any evaluation data for the flag.

To resolve this issue, your developers complete the following steps:

1. Confirm that the SDK evaluates the correct flag key in the application code.
2. Trigger the code path where the flag evaluation occurs so real traffic reaches LaunchDarkly.
3. Verify that events are enabled in the SDK configuration.

After evaluations appear in the evaluations graph, the health check updates to “Flag is receiving evaluations.” This confirms that LaunchDarkly can track traffic for the guarded rollout.

Flag context kinds

Your flag should be encountering context kinds that match the randomization unit that you chose in the Target by menu for the guarded rollout. If a flag encounters other context kinds, LaunchDarkly cannot measure the performance of the rollout.

The flag context kind health check can have a status of:

• Flag is seeing [context kind]: The flag is being evaluated by contexts with the same kind as the guarded rollout’s randomization unit.
• Flag is not seeing [context kind]: The flag is being evaluated by contexts with a different context kind than the one you selected for the guarded rollout. Either update the guarded rollout’s randomization unit, or investigate why your flag is not encountering the context kinds you expect.

To learn more, read Randomization unit and Context kinds.

Example: Flag is not seeing the expected context kind

A guarded rollout uses organization as the randomization unit. The health check displays “Flag is not seeing organization.” This means that the evaluations reaching LaunchDarkly do not include the organization context kind.

Your developers investigate and discover that the frontend sends a multi-context with both user and organization. The backend sends only user. Because the rollout uses organization as the randomization unit, LaunchDarkly cannot measure performance until evaluations include the organization context kind.

To resolve this issue, your developers complete the following steps:

1. Update backend evaluations to include a multi-context that contains both user and organization.
2. Confirm in the LaunchDarkly UI that the organization context kind is marked as Available for experiments and guarded rollouts.

When LaunchDarkly begins receiving evaluations that include the organization context kind, the health check updates to “Flag is seeing organization.”

Metric randomization units

The metric randomization unit health check only appears if LaunchDarkly is receiving events for the metric.

Your selected metrics should use the same randomization unit that you chose in the Target by menu for the guarded rollout. If a metric is tracking a different randomization unit, LaunchDarkly cannot measure the performance of the rollout.

The metric randomization unit health check can have a status of:

• [Randomization unit] is tracked by [Metric name]: The metric shares the same randomization unit as the one you selected for the guarded rollout.

• [Randomization unit] is not tracked by [Metric name]: The metric uses a different randomization unit than the one you selected for the guarded rollout. This can occur because randomization units are based on how the metric was configured, not on actual data sent to LaunchDarkly.

  For example, you might select Member as the randomization unit because it was available during setup. If your SDK does not send context data for Member, the metric cannot be evaluated.

  To fix this, choose a different metric, change the randomization unit for the rollout, or edit your metric configuration.

Example: Metric does not track the selected randomization unit

Your organization creates a guarded rollout and selects request as the randomization unit. Two latency metrics are attached. One metric uses request as the randomization unit. The other uses user because it was created earlier with a different configuration. The health check displays “request is not tracked by latency percentile.”

To resolve this issue, your developers complete the following steps:

1. Review the metric configuration to confirm which randomization unit it uses.
2. Decide how to align the metric with the guarded rollout. Update the metric to use request, choose a different metric, or change the rollout to target by user.
3. Save the updated configuration and verify that new metric events include the required context kind.

After LaunchDarkly receives metric events that match the request randomization unit, the health check updates to “request is tracked by latency percentile.”

Metric events

The metric events health check can have a status of:

• Recently seen events for [metric name]: Your metric has sent metric events to LaunchDarkly within the last 90 days. This means your metric was active and correctly sending data.
• No recently seen events for [metric name]: Your metric has not sent any metric events to LaunchDarkly within the last 90 days. This may indicate a misconfiguration or inactivity.

If metrics do not send events during a period of time, relative difference charts display a flat segment using the most recent value. This approach keeps the timeline continuous and ensures hover behavior remains smooth.

You can also check if a metric is sending events to LaunchDarkly by viewing its Activity tab.

Example: No recently seen events for a metric

A guarded rollout includes a conversion metric named “Checkout conversions.” The health check displays “No recently seen events for Checkout conversions.” When your developers check the metric Activity tab, they see that the metric last received events 90 days ago. The checkout flow changed recently and the SDK no longer sends the checkoutCompleted event that the metric expects.

To resolve this issue, your developers complete the following steps:

1. Verify the event name, properties, and context data in the SDK code.
2. Update the event tracking so that the checkoutCompleted event is sent again.
3. Review the Activity tab to confirm that LaunchDarkly is receiving new metric events.

After events begin flowing, the health check updates to “Recently seen events for Checkout conversions.” The relative difference chart begins reflecting new data from the rollout.