メインコンテンツまでスキップ

予算予約 — アラートのランブック (ADR-0001 §7)

永続的な予算予約の可観測性に関する、運用者向けリファレンスです。メトリクス(§7.2)、照合ワーカーの不変条件チェック(§7.1.3/§7.1.4)、決済遅延のウォッチドッグ(§5.4)、および D17 のシャドウ終了ゲートの入力(§7.3)を扱います。以下のルールは、deploy/prometheus/alert-rules.yml へそのままコピー&ペーストできます。

出典:

  • loggerd の照合ワーカー(pkg/budget/reconcile.go、コンポーネント budget-reconcile)— 失効したエスクローを解放します(§7.1.1/§7.1.2)。パスごとに不変条件のゲージと決済遅延をエクスポートします(デフォルトは 5 分ごと)。決済ワーカーが動く場所ならどこでも動きます。loggerd が停止しているときは何も解放されません(§5.4、保守的です)— その盲点こそが、決済遅延のアラートが見ているものです。
  • ゲートウェイのアドミッション層(pkg/budget/admission.go、コンポーネント budget-admission)— grant/admit の結果、追加されたレイテンシ、および bound の違反(§4.2)。

1. メトリクスリファレンス(§7.2)​

系列型生成元意味
budget_reserved_micro_usd{scope_kind}gauge照合ハードスコープごとの、予約によって凍結された容量(wallet/team_month/agent_day/session)。
budget_allowance_released_total{reason}counter照合解放: expired_safety_window(レプリカが死に、リースが 2 時間を超えて失効)/zero_remainder(ドレイン中または期限切れ。返すものがありません)。
budget_reserved_divergence_micro_usd{scope_kind}gauge照合§7.1.3 の逸脱: Σ|reserved(row) − その行の未解放アローワンスの残差の Σ|。資金を保存する経路では、これは 0 のままです。
budget_wallet_headroom_micro_usdgauge照合組織をまたぐ §7.1.4 の左辺の最悪値: min(balance − remainder − floor − reserved)。
budget_wallet_invariant_violationsgauge照合§7.1.4 のヘッドルームが負である組織の数(組織名は loggerd のログにあり、ラベルには決して入りません)。
budget_stranded_micro_usdgauge照合失効した未解放アローワンスによって凍結された容量(§12)。死んだレプリカは、最大 2 時間 + TTL のあいだ資金をブロックします。
settlement_lag_secondsgauge照合最も古い未決済の決済ジョブ(pending/retry/processing)の経過時間。
budget_grants_total{scope_kind,result}counterゲートウェイgranted/insufficient/no_source/error(ストア障害)。
budget_grant_duration_secondshistogramゲートウェイPG の grant レイテンシ。
budget_local_admit_total{result}counterゲートウェイReserve がリクエストへどう資金を出したか: local/grant/refused。
budget_admission_overhead_secondshistogramゲートウェイこの層が追加する同期アドミッションのレイテンシ(Plan + Reserve)。D17 ゲート: p95 ≤ 5 ms。
budget_bound_violation_total{scope_kind}counterゲートウェイactual > bound で確定したリクエスト(§4.2)— 正当な超過支出の唯一の発生源です。
budget_bound_overshoot_micro_usd_total{scope_kind}counterゲートウェイ累積された (actual − bound)+。単位は µUSD。
gateway_reservations_would_deny_total{scope_kind}counterゲートウェイ (NEXT-18c)ADR の budget_would_deny_total。シャドウで観測された拒否(D17 終了レポートの入力)。
gateway_reservations_denied_total{scope_kind}counterゲートウェイ (NEXT-18c)enforce で適用された拒否(402/429/403)。
gateway_would_bill_partial_micro_usd_total{scope_kind}counter決済 (NEXT-18d)ADR の would_bill_partial_micro_usd_total。enforce が請求するであろう部分使用のコスト。シャドウで観測されます。
gateway_uncharged_unknown_total{scope_kind}counter決済 (NEXT-18d)使用量が不明なイベントの予約済み bound。請求されることはなく、ここで見えます。
gateway_settlement_batch_sizehistogram決済 (NEXT-18d)組織バッチの決済 TX あたりのジョブ数。
gateway_settlement_jobs_backlog{state}gauge決済 (AF-06)状態別のバックログ。requires_attention は永続的な負債です。

ラベルに組織/キー/セッションの識別子が現れることは決してありません(カーディナリティとプライバシーのルール AF-16)。組織ごとの値は管理 API の仕事です。

2. アラートルール​

BudgetSettlementLagHigh — warning → critical(§5.4)​

- alert: BudgetSettlementLagHigh
expr: settlement_lag_seconds > 1800
for: 5m
labels:
severity: warning
annotations:
summary: "Settlement lag above 30 minutes"
description: "Oldest unsettled settlement job is {{ $value | humanizeDuration }} old."

§5.4: 遅延が 30 分を超えると、決済ワーカーが停滞していることを意味します。停滞しているあいだ、照合は保守的に何も解放しません(予約は凍結されたままです — 安全な方向です)。停滞したワーカーは請求も遅らせます。30 分後に critical へエスカレーションします(for: 30m の複製)— 二重障害(死んだレプリカ + 2 時間の安全ウィンドウを超えて停滞した loggerd)は、死んだレプリカの未計上の支出の分だけ、利用可能な容量を一時的に過大表示することがあります。

対応: gateway_settlement_jobs_backlog{state=~"pending|retry|processing"} と決済ワーカーのログを確認してください。ワーカーが停止していれば loggerd を再起動します。照合は自動的に再開します。手動の解放が必要になることは決してありません。

BudgetScopeReserveDivergence — critical(§7.1.3)​

- alert: BudgetScopeReserveDivergence
expr: max by (scope_kind) (budget_reserved_divergence_micro_usd) > 0
for: 10m
labels:
severity: critical
annotations:
summary: "Reserved-money invariant divergence ({{ $labels.scope_kind }})"
description: "reserved_µ(S) ≠ Σ remainders of non-released allowances; {{ $value }} µUSD unexplained."

資金の不変条件 reserved_µ(S) = Σ remainders of non-released allowances は、すべてのコード経路(組織ごとのアドバイザリロックのもとでの grant/return/settle/release のコミット)で成立します。10 分間持続する任意の非ゼロ値はドリフトです。バグか、手動の改ざんです。解放経路はロックのもとで再チェックするため、照合が乖離を広げることはありません。ドリフトを「超えて」解放すると、容量は安全な方向へ凍結され、reconcile reserve decrement failed; releasing anyway がログされます。

対応: loggerd のログで scope reserve invariant divergence と reconcile reserve decrement failed を grep してください(行はスコープ/キーを含みます)。次に、示されたキーについて budget_allowances とスコープ行の reserved_micro_usd を突き合わせます。請求のオーナーへエスカレーションしてください。予約を手で編集しないでください — 乖離しているライターを直し、照合を再実行します。

BudgetWalletInvariantBreach — critical(§7.1.4)​

- alert: BudgetWalletInvariantBreach
expr: budget_wallet_invariant_violations > 0
for: 15m
labels:
severity: critical
annotations:
summary: "Wallet invariant breached on {{ $value }} org(s)"
description: "balance − floor − reserved < 0 sustained beyond the bound-overshoot window (§7.1.4)."

一時的な落ち込みは正当です。bound のオーバーシュート(推定誤差、§4.2)は、オーバーシュートが決済され照合がエスクローをクリアするまで、balance − floor − reserved をゼロ未満へ引き下げられます — これが §7.1.4 のウィンドウです。15 分間連続した違反は、通常の決済レイテンシを超えており、記録されたオーバーシュートを超える超過支出か、予約会計のドリフトのいずれかを意味します。

対応: increase(budget_bound_overshoot_micro_usd_total[30m]) を budget_wallet_headroom_micro_usd と突き合わせてください。組織は loggerd のログにあります(wallet invariant violation (§7.1.4)、組織 id を含みます)。オーバーシュートで説明できる場合は、そのモデルの bound 推定を見直す必要があります(D17 の入力を参照)。そうでない場合は、予約のドリフトとして扱います(乖離アラートを参照)。

BudgetWalletHeadroomNegative — warning(前兆)​

- alert: BudgetWalletHeadroomNegative
expr: budget_wallet_headroom_micro_usd < 0
for: 5m
labels:
severity: warning
annotations:
summary: "Worst-case wallet headroom is negative"

上の逸脱の早期シグナルです(一時ウィンドウ内にある 1 つ以上の組織)。監視してください。ページは出さないでください。

BudgetStrandedCapacityHigh — warning(§12)​

- alert: BudgetStrandedCapacityHigh
expr: budget_stranded_micro_usd > 10000000
for: 30m
labels:
severity: warning
annotations:
summary: "Stranded reservation capacity {{ $value | humanize }}µUSD"
description: "Dead/lost replicas keep freezing capacity (released after TTL 10m + safety 2h)."

対応: 死んだレプリカを特定します(budget_allowances の未解放行で lease_until < now()。replica_id は host:boot を表します)。再起動するかドレインしてください。照合は安全ウィンドウのあと自動的に解放します。死んだレプリカがないのに滞留した容量が続く場合 → 更新ループが壊れています(ゲートウェイのログ reservation renewal failed を確認してください)。

BudgetExpiredReleaseSpike — warning(レプリカの停止)​

- alert: BudgetExpiredReleaseSpike
expr: increase(budget_allowance_released_total{reason="expired_safety_window"}[1h]) > 10
for: 5m
labels:
severity: warning
annotations:
summary: "Multiple allowances released past the safety window"
description: "Replicas are dying (or losing renewal) without graceful drain."

対応: ゲートウェイレプリカの導入/OOM kill と相関させてください。ゆるやかな背景レートはオートスケールでは正常です。スパイクは安定性のシグナルです。

BoundViolationRateHigh — D17 ゲートの監視(§7.3)​

- alert: BoundViolationRateHigh
expr: >
sum(increase(budget_bound_violation_total[7d]))
/ clamp_min(sum(increase(budget_local_admit_total{result=~"local|grant"}[7d])), 1) > 0.001
for: 1h
labels:
severity: warning
annotations:
summary: "Bound-violation rate above 0.1% of reserved requests (D17 gate)"

D17 のシャドウ終了は、連続 7 日間で ≤ 0.1% を要求します。このアラートはお金についてはページしません(オーバーシュートは猶予で吸収され、budget_bound_overshoot_micro_usd_total がその大きさを示します)— 発火しているあいだはシャドウ終了レポートをブロックします。

対応: 違反したモデルについて、リクエストイベントから bound 推定フィールド(in_est、out_cap、モデル)を取り出してください。終了を再試行する前に InputMargin/default_output_cap_tokens(§4.3)を見直します。

AdmissionOverheadP95High — D17 ゲートの監視(§7.3)​

- alert: AdmissionOverheadP95High
expr: histogram_quantile(0.95, sum by (le) (rate(budget_admission_overhead_seconds_bucket[1h]))) > 0.005
for: 30m
labels:
severity: warning
annotations:
summary: "Reservation admission p95 overhead above 5ms (D17 gate)"

対応: まず budget_grant_duration_seconds の p95 を確認してください(grant はオーバーヘッドの内側にある PG のラウンドトリップです)。あわせて PG の健全性も確認します。アドミッションがレイテンシを足すのは予約経路だけです(キャッシュミス)。grant が安定しているのに上昇している場合は、組織設定/プローブのキャッシュ(TTL 5 秒)が冷えていることを指します。

ReservationGrantErrors — warning(§5.4)​

- alert: ReservationGrantErrors
expr: sum(rate(budget_grants_total{result="error"}[10m])) > 0
for: 10m
labels:
severity: warning
annotations:
summary: "Reservation store errors during grant"
description: "PG unreachable for grants — enforce orgs get 503 budget_store_unavailable once local escrow drains (D9/D14)."

対応: PG への接続を復旧してください。result="insufficient" と result="no_source" は通常の拒否(枯渇/予算行の欠落)であり、障害ではありません。

3. D17 シャドウ終了レポートの入力(§7.3)​

シャドウ下の組織について、連続 7 日間:

  1. sum(increase(budget_bound_violation_total[7d])) / sum(increase(budget_local_admit_total{result=~"local|grant"}[7d])) ≤ 0.001;
  2. 累積オーバーシュート increase(budget_bound_overshoot_micro_usd_total[7d]) ≤ 組織の |grace_floor|(組織ごとの値は管理 API 経由);
  3. p95 の budget_admission_overhead_seconds ≤ 0.005;
  4. gateway_reservations_would_deny_total と gateway_would_bill_partial_micro_usd_total を内訳し、すべての理由を処分済みにします(価格未設定のモデルは価格を付けるか、意識的に拒否します)。

4. 注記​

  • 照合パスの間隔(デフォルト 5 分)は、照合側のすべてのゲージを量子化します。上のルールの for: の長さは、すでにそれを織り込んでいます。
  • released のアローワンスの保持期間はデフォルト 90 日です(決済済みの決済ジョブの保持と同じ地平、AF-16)。境界のあるバッチで終端の released 行だけを削除します。ライブ状態には決して触れません。
  • グローバルなキルスイッチ YABANIN_RESERVATIONS=off は、新しい予約を停止します(モードのクランプ、§9)。既存の割り当ては照合を通じてドレインします。