flag-monitoring

flag-monitoring

GrowthBook のフィーチャーフラグで、監視付きの段階的ロールアウト（「セーフロールアウト」とも呼ばれます）を設定、管理します。セーフロールアウトは、複数ステップの段階的な拡大スケジュールと monitoringConfig を設定した標準の rollout ルールです。監視機能は各ステップでガードレール指標を監視し、回帰が検出された場合にロールバックを通知または自動実行します。

すべての API 呼び出しは、同梱のヘルパー ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call を経由します。GB_API_KEY を環境変数に設定するか、/growthbook:gb-setup で ~/.config/growthbook/.env に書き込む必要があります。

監視設定に必要な入力

設定する前に、次の情報を収集します。

• データソース ID — エクスポージャーイベントと指標イベントを追跡するデータソース
• エクスポージャークエリ ID — ロールアウト対象のユーザーを特定する割り当てクエリ
• ガードレール指標 ID — 回帰してはならない指標（例：エラー率、クラッシュ率）を1つ以上
• シグナル指標 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 — 監視付きランプを作成する（ランプ構成と監視をまとめて設定）

monitoringConfig を含むランプスケジュールの完全なペイロードを作成し、1回の PUT で送信します。新しいランプの作成と、公開前に既存のドラフトのランプを更新する場合の両方に対応します。

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 に引き継ぎます。

Path 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"）、ガードレールの健全性、現在のステップが承認待ちかどうかが返されます。<rs-id> は、フラグのルール（rampScheduleId）から取得するか、次の方法で取得してください。

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 Path D を参照してください。

ガードレール

• ドラフトバージョンの引き継ぎ。 このセッションで以前の書き込みスキルからバージョン番号を引き継いでいる場合は、new ではなく、その番号を明示的に使用してください。新たに開始する場合は new を使用してください。
• 対象環境でフラグが有効になっていることを確認する。 対象環境でフラグが無効になっていると、ランプは機能しません。警告を出し、まず flag-toggle に進んでください。
• autoUpdate は、モニタリング付きランプスケジュールの monitoringConfig で自動ロールバックを制御します。デフォルトは true（ガードレール違反時に自動でロールバック）です。
• startDate は省略可能です — ユーザーが明示的に開始を遅らせたい場合を除き、省略してください。ほとんどのチームでは、公開が成功したことを確認した後、ユーザーの操作でランプを開始します。
• cutoffDate を使うケースは限られます — ユーザーから尋ねられない限り、言及しないでください。
• ガードレールメトリクスが少なくとも 1 つ必要です。 ガードレールなしのモニタリングは単なる観察です。ユーザーがガードレールメトリクスを指定できない場合は、代わりにモニタリングなしのランプ（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 }）
• アクションの全リファレンス（pause、resume、complete、restart）については、flag-ramp のパス D を参照してください

引き継ぎ先

• flag-ramp — モニタリングなしでランプステップの構成を管理する場合
• flag-toggle — モニタリング中のロールアウトで緊急キルスイッチを使用する場合
• flag-targeting — モニタリングを設定する前にルール条件を構成する場合
• flag-publish — ドラフトを公開して、モニタリング対象のロールアウトを有効にする場合