flag-monitoring

flag-monitoring

为 GrowthBook 功能标志设置并管理受监控的渐进式发布（也称为“安全发布”）。安全发布是一条标准的 rollout 规则，带有多步骤渐进计划并附加了 monitoringConfig——监控会在每个步骤检查护栏指标，并在检测到回归时发出信号或自动触发回滚。

所有 API 调用都通过随附的辅助脚本：${CLAUDE_PLUGIN_ROOT}/scripts/gb-call。需要在环境变量中设置 GB_API_KEY，或通过 /growthbook:gb-setup 将其写入 ~/.config/growthbook/.env。

监控配置所需输入

配置前，请收集：

• 数据源 ID — 跟踪曝光和指标事件的数据源
• 曝光查询 ID — 用于识别发布中用户的分配查询
• 护栏指标 ID — 至少一个不得出现回归的指标（例如错误率、崩溃率）
• 信号指标 ID（可选）— 要监控的先行指标，不作为硬性门槛
• SRM 操作 — 样本比例不匹配时的处理方式："hold"（推荐——暂停以供检查）、"rollback"（较激进）或 "warn"
• 自动回滚（受监控渐进计划负载中的 autoUpdate，安全发布中的 autoRollback）— true 表示护栏检查失败时系统会在未经人工批准的情况下回滚；false 表示暂停并等待人工审核。除非用户担心查询成本，或希望手动控制监控快照的频率，否则默认设为 true

# Resolve datasource and exposure query IDs:
gb-call GET /api/v1/data-sources

# Resolve metric IDs — query both: fact metrics and legacy metrics are separate endpoints,
# and most orgs keep guardrail/signal metrics as fact metrics:
gb-call GET '/api/v1/fact-metrics?datasourceId=<ds-id>&limit=100'
gb-call GET '/api/v1/metrics?datasourceId=<ds-id>&limit=100'

工作流

路径 A — 创建受监控的渐进计划（同时设置渐进结构和监控）

在单个 PUT 请求中构建包含 monitoringConfig 的完整渐进计划负载。这适用于新建渐进计划，也适用于发布前更新现有草稿的渐进计划。

1. 收集渐进步骤 — 请参阅 flag-ramp，了解步骤和间隔的设计指导。

2. 收集监控配置（见上方“监控配置所需输入”）：

gb-call GET /api/v1/data-sources
gb-call GET '/api/v1/fact-metrics?datasourceId=<ds-id>&limit=100'
gb-call GET '/api/v1/metrics?datasourceId=<ds-id>&limit=100'

3. PUT 完整负载（同时包含步骤和监控配置）：

echo '{
  "startActions": [
    { "targetType": "feature-rule", "targetId": "<rule-id>", "patch": { "coverage": 0 } }
  ],
  "steps": [
    {
      "interval": 86400,
      "monitored": true,
      "actions": [{ "targetType": "feature-rule", "targetId": "<rule-id>", "patch": { "coverage": 0.1 } }]
    },
    {
      "interval": 86400,
      "monitored": true,
      "holdConditions": { "requiresApproval": true },
      "actions": [{ "targetType": "feature-rule", "targetId": "<rule-id>", "patch": { "coverage": 0.5 } }]
    }
  ],
  "endActions": [
    { "targetType": "feature-rule", "targetId": "<rule-id>", "patch": { "coverage": 1.0 } }
  ],
  "monitoringConfig": {
    "datasourceId": "<ds-id>",
    "exposureQueryId": "<query-id>",
    "guardrailMetricIds": ["<metric-id>"],
    "signalMetricIds": ["<metric-id>"],
    "autoUpdate": true,
    "srmAction": "hold",
    "noTrafficAction": "warn",
    "noTrafficGracePeriodHours": 24,
    "multipleExposureAction": "warn"
  }
}' | gb-call PUT /api/v2/features/<flag-id>/revisions/new/rules/<rule-id>/ramp-schedule -

startActions 将覆盖率设为 0（回滚锚点）。步骤上的 monitored: true 表示渐进计划需等待监控结果后才能自动进入下一步——只有在存在 monitoringConfig 时才会生效。步骤 2 上的 holdConditions.requiresApproval 会在间隔结束且监控通过后增加一道人工审核关卡。

autoUpdate: true 会在护栏检查失败时自动回滚。只有当用户希望手动控制监控频率或担心查询成本时，才提及 autoUpdate: false。

除非用户明确要求延迟启动，否则省略 startDate。

4. 交由 flag-publish 处理。

路径 B — 检查监控状态或响应信号

采取任何操作之前，请打开功能页面 — 该页面会显示渐进步骤进度、护栏和信号指标健康状况、实验级健康检查（SRM、多次曝光、无流量），以及包含效应量和置信区间的完整指标表现细分。API /status 端点会提供 decision，而 UI 会提供决策所需的上下文：

# macOS:
open <host>/features/<flag-id>
# Linux:
xdg-open <host>/features/<flag-id>

通过 API 检查状态（适用于脚本化流水线，或用户希望快速获取决策信号时）：

gb-call GET /api/v1/ramp-schedules/<rs-id>/status

返回 decision（"advance" / "hold" / "rollback" / "waiting"）、护栏健康状况，以及当前步骤是否正在等待审批。从标志的规则（rampScheduleId）中获取 <rs-id>，或使用：

gb-call GET '/api/v1/ramp-schedules?featureId=<flag-id>'

批准受监控的等待审批步骤（间隔已过且监控显示健康时）：

gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/approve-step

如果监控尚未产生最新的健康结果，或间隔仍在计时，则返回 400 — 请先轮询 /status。

越过监控暂停继续推进（决策为 "hold"，且你已检查信号并接受风险时）：

echo '{}' | gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/advance -

护栏失败时回滚（当 decision: "rollback" 或护栏未通过时）：

echo '{"reason":"<description of what failed>"}' | gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/rollback -

紧急停止（最快方式 — 通过 flag-toggle 禁用标志环境，无需渐进计划 ID）。

打开 UI 查看可视化健康状况仪表板：

# macOS:
open <host>/features/<flag-id>
# Linux:
xdg-open <host>/features/<flag-id>

完整的实时渐进管理操作参考（暂停、恢复、完成、重启），请参阅 flag-ramp 路径 D。

护栏

• 草稿版本传递。 如果本次会话中先前的写入技能已将版本号纳入上下文，请显式使用该版本号，而不要使用 new。从头开始时则使用 new。
• 检查目标环境是否已启用。 如果目标环境中的标志已禁用，渐进将不会生效 — 请发出警告，并先转到 flag-toggle。
• autoUpdate 控制受监控渐进计划的 monitoringConfig 中是否自动回滚。默认值为 true（护栏失败时自动回滚）。
• startDate 为可选项 — 除非用户明确要求延迟开始，否则请省略。大多数团队会在确认发布成功后，通过用户操作启动渐进。
• cutoffDate 适用场景较少 — 除非用户询问，否则不要提及。
• 至少需要一个护栏指标。 没有护栏的监控只是观察 — 如果用户无法提供护栏指标，建议改用无监控渐进（flag-ramp）。
• 指标必须位于同一数据源。 monitoringConfig 中的 datasourceId 必须与定义护栏指标的数据源一致。如果它们位于不同数据源，API 将拒绝该配置。
• autoUpdate: true 表示系统会在未经人工批准的情况下回滚。 仅当用户希望手动控制监控频率或担心查询成本时，才提及 autoUpdate: false。
• 对于设置了 holdConditions.requiresApproval 的受监控步骤： 每次步骤暂停后，都需要人工明确批准，渐进才能继续。
• SRM 操作的默认值很重要。 对 SRM 使用 "rollback" 属于激进做法。"hold" 更安全 — 渐进会暂停，以便人工检查。除非用户明确希望采取激进保护措施，否则建议对 SRM 使用 "hold"。

交叉链接

此技能会协调以下技能：

• flag-ramp — 用于构建渐进计划结构（步骤、间隔、开始／截止日期）。构建自定义步骤序列时，请参阅 flag-ramp。
• flag-schedule — 用于设置渐进开始时间（在渐进计划上设置 startDate）。
• flag-targeting — 用于为正在渐进的规则设置定向条件。
• flag-toggle — 监控信号表明存在严重问题时，用作紧急终止开关。

使用的端点

草稿（发布前）：

• GET /api/v2/features/:id — 获取功能开关和当前规则
• GET /api/v1/data-sources — 解析数据源 ID
• GET /api/v1/fact-metrics?datasourceId=…、GET /api/v1/metrics?datasourceId=… — 解析护栏和信号指标 ID（事实指标和旧版指标使用不同的端点）
• PUT /api/v2/features/:id/revisions/new/rules/:ruleId/ramp-schedule — 使用 monitoringConfig 创建或更新渐进发布计划

实时渐进发布管理：

• GET /api/v1/ramp-schedules — 列出渐进发布计划（筛选条件：featureId、ruleId）
• GET /api/v1/ramp-schedules/:id/status — 实时健康状况、决策和各指标影响
• POST /api/v1/ramp-schedules/:id/actions/approve-step
• POST /api/v1/ramp-schedules/:id/actions/advance（请求体：可选的 { force: true }）
• POST /api/v1/ramp-schedules/:id/actions/rollback（请求体：{ reason: string }）
• 完整的操作参考（暂停、恢复、完成、重新启动）请参阅 flag-ramp 的路径 D

交接

• flag-ramp — 用于管理渐进发布步骤结构，不含监控
• flag-toggle — 用于在实时监控发布期间执行紧急停用
• flag-targeting — 用于在设置监控之前配置规则条件
• flag-publish — 用于发布草稿并激活受监控的渐进发布