launchdarkly-guarded-rollout

LaunchDarkly Guarded Rollouts

你正在使用一项技能，该技能将指导你配置 LaunchDarkly 中的受保护发布。你的任务是设计发布阶段、选择监控指标、配置回归阈值，并启动发布。

前提条件

此技能要求在你的环境中配置远程托管的 LaunchDarkly MCP 服务。

必需的 MCP 工具：

• start-guarded-rollout -- 启动带监控的渐进式发布
• get-flag -- 检查标志及其变体
• list-metrics -- 查找发布期间要监控的指标

可选的 MCP 工具：

• stop-guarded-rollout -- 立即停止正在进行的发布
• toggle-flag -- 确保启动前标志已开启
• create-metric -- 创建尚不存在的指标

核心概念

什么是受保护发布？

受保护发布会通过一系列阶段，逐步增加新功能标志变体的流量。每个阶段中，LaunchDarkly 都会监控选定的指标，以发现回归。如果检测到回归，发布可以自动暂停并通知团队，甚至回滚。

关键组成部分

组成部分	描述
测试变体	正在发布的新变体
对照变体	现有／基准变体
阶段	流量百分比逐步增加并设有监控窗口的步骤
指标	要监控的回归指标（错误率、延迟等）
回归阈值	触发操作前指标允许恶化的幅度
回归时的操作	超出阈值时是通知、回滚还是两者都执行

发布权重单位

发布权重以千分之一为单位（基点）：

• 1000 = 1%
• 10000 = 10%
• 50000 = 50%
• 100000 = 100%

监控窗口

监控窗口以毫秒为单位指定：

• 3600000 = 1 小时
• 86400000 = 24 小时
• 604800000 = 7 天

核心原则

1. 从小规模开始：从较低的百分比（1-5%）开始，尽早发现问题
2. 监控关键指标：选择能够反映用户体验的指标
3. 设置合理的阈值：过严会导致误报；过宽则可能漏掉回归
4. 留出足够时间：每个阶段都需要足够的监控时间，以便信号显现
5. 制定回滚计划：务必至少配置回归时的通知

工作流

步骤 1：准备

启动受保护发布前：

1. 使用 get-flag 检查标志——记下测试和对照变体的 ID
2. 使用 list-metrics 查找适合监控的指标
3. 确保目标环境中的标志已开启（如有需要，使用 toggle-flag）
4. 确认此标志当前没有正在进行的受保护发布

步骤 2：设计阶段

规划发布进度。常见模式如下：

阶段	流量	监控窗口	目的
1	1%	1 小时	冒烟测试——发现明显的崩溃
2	10%	24 小时	初步了解指标信号
3	50%	24 小时	建立信心
4	100%	24 小时	在监控下全面发布

步骤 3：配置指标

选择能够反映问题的指标：

指标类型	示例	阈值	操作
错误率	api-error-rate	0.05（增加 5%）	回滚
延迟	p99-response-time	0.2（增加 20%）	通知
转化率	checkout-completed	0.1（下降 10%）	通知 + 回滚

步骤 4：启动发布

使用 start-guarded-rollout：

{
  "projectKey": "my-project",
  "flagKey": "new-checkout-flow",
  "environmentKey": "production",
  "testVariationId": "variation-id-for-new-flow",
  "controlVariationId": "variation-id-for-current-flow",
  "randomizationUnit": "user",
  "stages": [
    {"rolloutWeight": 1000, "monitoringWindowMilliseconds": 3600000},
    {"rolloutWeight": 10000, "monitoringWindowMilliseconds": 86400000},
    {"rolloutWeight": 50000, "monitoringWindowMilliseconds": 86400000},
    {"rolloutWeight": 100000, "monitoringWindowMilliseconds": 86400000}
  ],
  "metrics": [
    {
      "metricKey": "api-error-rate",
      "onRegression": {"notify": true, "rollback": true},
      "regressionThreshold": 0.05
    },
    {
      "metricKey": "checkout-completed",
      "onRegression": {"notify": true, "rollback": false},
      "regressionThreshold": 0.1
    }
  ]
}

步骤 5：验证

1. 使用 get-flag 确认受保护发布已启动
2. 检查标志是否显示环境中的发布配置
3. 监控是否收到任何即时回归通知

报告结果：

• 已启动包含 N 个阶段的受保护发布
• 正在监控 M 个指标
• 第一阶段流量为 X%，持续 Y 小时

停止发布

如果出现问题或需要停止发布：

{
  "projectKey": "my-project",
  "flagKey": "new-checkout-flow",
  "environmentKey": "production"
}

这会立即停止渐进式发布，并将标志锁定在当前状态。

边缘情况

情况	操作
标志已关闭	先使用 toggle-flag 将其开启——发布要求标志处于开启状态
存在正在进行的发布	开始新发布前，先使用 stop-guarded-rollout 停止当前发布
没有合适的指标	先使用 create-metric 创建指标
需要审批	如果环境要求审批，工具会返回审批 URL

不要做的事

• 不要对已关闭的标志启动受保护发布
• 不要跳过监控窗口设计——匆忙推进各阶段会违背发布的初衷
• 不要将回归阈值设为 0——轻微波动很正常
• 不要忘记配置至少一个指标——没有监控的发布只是普通发布