Skip to main content

Tempahan Bajet — Runbook Amaran (ADR-0001 §7)

Rujukan operator bagi kebolehcerapan tempahan bajet yang tahan lama: metrik (§7.2), semakan invarian pekerja reconcile (§7.1.3/§7.1.4), pengawas kelewatan penyelesaian (§5.4) dan input pintu keluar bayang D17 (§7.3). Peraturan di bawah sedia untuk salin-tampal ke deploy/prometheus/alert-rules.yml.

Sumber:

  • pekerja reconcile loggerd (pkg/budget/reconcile.go, komponen budget-reconcile) — melepaskan escrow yang luput (§7.1.1/§7.1.2), mengeksport tolok invarian dan kelewatan penyelesaian pada setiap laluan (lalai setiap 5 min). Ia berjalan di mana sahaja pekerja penyelesaian berjalan; apabila loggerd jatuh tiada apa-apa dilepaskan (§5.4, konservatif) — titik buta itu tepat apa yang dipantau oleh amaran kelewatan penyelesaian.
  • lapisan kemasukan gerbang (pkg/budget/admission.go, komponen budget-admission) — hasil geran/kemasukan, kependaman tambahan dan pelanggaran batas (§4.2).

1. Rujukan metrik (§7.2)​

SiriJenisPengeluarMaksud
budget_reserved_micro_usd{scope_kind}tolokreconcileKapasiti yang dibekukan oleh tempahan bagi setiap skop keras (wallet/team_month/agent_day/session).
budget_allowance_released_total{reason}kaunterreconcilePelepasan: expired_safety_window (replika mati, pajakan luput melepasi 2 jam) / zero_remainder (sedang disalirkan/tamat tempoh, tiada apa untuk dipulangkan).
budget_reserved_divergence_micro_usd{scope_kind}tolokreconcilePelanggaran §7.1.3: Σ|reserved(row) − Σ baki elaun belum dilepaskan bagi baris itu|. Laluan yang memelihara wang mengekalkan ini pada 0.
budget_wallet_headroom_micro_usdtolokreconcileLHS kes terburuk §7.1.4 merentas organisasi: min(balance − remainder − floor − reserved).
budget_wallet_invariant_violationstolokreconcileKiraan organisasi dengan ruang kepala §7.1.4 negatif (organisasi dinamakan dalam log loggerd, tidak pernah dalam label).
budget_stranded_micro_usdtolokreconcileKapasiti yang dibekukan oleh elaun belum dilepaskan yang luput (§12): replika mati menyekat wang sehingga 2 jam + TTL.
settlement_lag_secondstolokreconcileUmur kerja penyelesaian tertua yang belum diselesaikan (pending/retry/processing).
budget_grants_total{scope_kind,result}kauntergerbanggranted / insufficient / no_source / error (gangguan stor).
budget_grant_duration_secondshistogramgerbangKependaman geran PG.
budget_local_admit_total{result}kauntergerbangCara Reserve membiayai permintaan: local / grant / refused.
budget_admission_overhead_secondshistogramgerbangKependaman kemasukan segerak yang ditambah oleh lapisan (Plan + Reserve). Pintu D17: p95 ≤ 5 ms.
budget_bound_violation_total{scope_kind}kauntergerbangPermintaan yang dimuktamadkan dengan actual > bound (§4.2) — satu-satunya sumber terlebih belanja yang sah.
budget_bound_overshoot_micro_usd_total{scope_kind}kauntergerbangTerkumpul (actual − bound)+ dalam µUSD.
gateway_reservations_would_deny_total{scope_kind}kauntergerbang (NEXT-18c)budget_would_deny_total ADR: penolakan yang diperhatikan dalam bayang (input laporan keluar D17).
gateway_reservations_denied_total{scope_kind}kauntergerbang (NEXT-18c)Penolakan yang dikenakan dalam enforce (402/429/403).
gateway_would_bill_partial_micro_usd_total{scope_kind}kaunterpenyelesaian (NEXT-18d)would_bill_partial_micro_usd_total ADR: kos penggunaan separa yang akan dibilkan oleh enforce, diperhatikan dalam bayang.
gateway_uncharged_unknown_total{scope_kind}kaunterpenyelesaian (NEXT-18d)Batas terpelihara peristiwa penggunaan tidak diketahui — tidak pernah dibilkan, kelihatan di sini.
gateway_settlement_batch_sizehistogrampenyelesaian (NEXT-18d)Kerja bagi setiap TX penyelesaian kelompok organisasi.
gateway_settlement_jobs_backlog{state}tolokpenyelesaian (AF-06)Tunggakan mengikut keadaan; requires_attention ialah hutang tahan lama.

Tiada pengecam organisasi/kunci/sesi pernah muncul dalam label (peraturan kardinaliti dan privasi AF-16); nilai per organisasi ialah tugas API pentadbir.

2. Peraturan amaran​

BudgetSettlementLagHigh — amaran → kritikal (§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: kelewatan > 30 min bermakna pekerja penyelesaian terhenti. Semasa ia terhenti, reconcile secara konservatif tidak melepaskan apa-apa (rizab kekal beku — arah selamat); pekerja yang terhenti juga melambatkan pengebilan. Naik taraf kepada critical selepas 30 min (klon for: 30m) — gangguan berganda (replika mati + loggerd terhenti melepasi tetingkap keselamatan 2 jam) boleh buat sementara melebihkan kapasiti tersedia oleh perbelanjaan replika mati yang tidak dikira.

Tindakan: semak gateway_settlement_jobs_backlog{state=~"pending|retry|processing"} dan log pekerja penyelesaian; mulakan semula loggerd jika pekerja jatuh. Reconcile disambung semula secara automatik; pelepasan manual tidak pernah diperlukan.

BudgetScopeReserveDivergence — kritikal (§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."

Invarian wang reserved_µ(S) = Σ remainders of non-released allowances kekal pada setiap laluan kod (komit geran/pulangan/selesai/lepas di bawah kunci advisory per organisasi). Mana-mana nilai bukan sifar yang berterusan selama 10 min ialah hanyutan: pepijat atau gangguan manual. Laluan pelepasan menyemak semula di bawah kunci, jadi reconcile tidak pernah melebarkan perbezaan; melepaskan "melebihi" hanyutan membekukan kapasiti pada arah selamat dan mengelog reconcile reserve decrement failed; releasing anyway.

Tindakan: grep log loggerd bagi scope reserve invariant divergence dan reconcile reserve decrement failed (baris membawa skop/kunci), kemudian budget_allowances berbanding reserved_micro_usd baris skop bagi kunci yang dinamakan. Naikkan kepada pemilik pengebilan; jangan sunting rizab dengan tangan — baiki penulis yang menyimpang dan jalankan semula reconcile.

BudgetWalletInvariantBreach — kritikal (§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)."

Penurunan sementara adalah sah: terlebih batas (ralat anggaran, §4.2) boleh menarik balance − floor − reserved di bawah sifar sehingga terlebih itu selesai dan reconcile membersihkan escrow — tetingkap §7.1.4. 15 min pelanggaran berterusan melebihi mana-mana kependaman selesai yang normal dan bermakna sama ada terlebih belanja melepasi terlebih yang direkod atau hanyutan perakaunan rizab.

Tindakan: semak silang increase(budget_bound_overshoot_micro_usd_total[30m]) terhadap budget_wallet_headroom_micro_usd; cari organisasi dalam log loggerd (wallet invariant violation (§7.1.4), membawa id organisasi). Jika dilindungi oleh terlebih: anggaran batas bagi model itu perlu semakan (lihat input D17). Jika tidak: layan sebagai hanyutan rizab (lihat amaran perbezaan).

BudgetWalletHeadroomNegative — amaran (petanda awal)​

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

Isyarat awal pelanggaran di atas (satu atau lebih organisasi di dalam tetingkap sementara). Pantau, jangan panggil orang bertugas.

BudgetStrandedCapacityHigh — amaran (§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)."

Tindakan: kenal pasti replika mati (baris budget_allowances yang belum dilepaskan dengan lease_until < now(); replica_id menamakan host:boot), mulakan semula atau salirkan mereka; reconcile melepaskan secara automatik selepas tetingkap keselamatan. Kapasiti terdampar yang berterusan tanpa replika mati → gelung pembaharuan rosak (semak log gerbang reservation renewal failed).

BudgetExpiredReleaseSpike — amaran (replika sedang mati)​

- 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."

Tindakan: kaitkan dengan pelaksanaan/pembunuhan OOM replika gerbang. Kadar latar yang lembut adalah normal bagi penskalaan automatik; lonjakan ialah isyarat kestabilan.

BoundViolationRateHigh — pemantau pintu 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)"

Keluar bayang D17 memerlukan ≤ 0.1% selama 7 hari berturut-turut. Amaran ini tidak memanggil orang bertugas kerana wang (terlebih diserap oleh kelonggaran, dan budget_bound_overshoot_micro_usd_total mengukur saiznya) — ia menyekat laporan keluar bayang semasa ia menyala.

Tindakan: tarik medan anggaran batas daripada peristiwa permintaan (in_est, out_cap, model) bagi model yang melanggar; semak InputMargin/default_output_cap_tokens (§4.3) sebelum mencuba keluar semula.

AdmissionOverheadP95High — pemantau pintu 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)"

Tindakan: semak p95 budget_grant_duration_seconds dahulu (geran ialah pusingan pergi-balik PG di dalam overhed) dan kesihatan PG; kemasukan hanya menambah kependaman pada laluan rizab (terlepas cache), jadi kenaikan dengan geran yang stabil menunjuk kepada cache tetapan organisasi/probe (TTL 5 s) yang sejuk.

ReservationGrantErrors — amaran (§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)."

Tindakan: pulihkan ketersambungan PG. result="insufficient" dan result="no_source" ialah penolakan biasa (kehabisan / baris bajet tiada), bukan gangguan.

3. Input laporan keluar bayang D17 (§7.3)​

Bagi organisasi di bawah bayang, 7 hari berturut-turut:

  1. sum(increase(budget_bound_violation_total[7d])) / sum(increase(budget_local_admit_total{result=~"local|grant"}[7d])) ≤ 0.001;
  2. terlebih terkumpul increase(budget_bound_overshoot_micro_usd_total[7d]) ≤ |grace_floor| organisasi (nilai per organisasi melalui API pentadbir);
  3. p95 budget_admission_overhead_seconds ≤ 0.005;
  4. gateway_reservations_would_deny_total dan gateway_would_bill_partial_micro_usd_total dipecahkan dan setiap sebab dilupuskan (model tanpa harga diberi harga atau ditolak secara sedar).

4. Nota​

  • Selang laluan reconcile (lalai 5 min) mengkuantumkan semua tolok sebelah reconcile; tempoh for: dalam peraturan di atas sudah mengambil kiraannya.
  • Pengekalan elaun released lalai kepada 90 hari (ufuk yang sama seperti pengekalan kerja penyelesaian yang telah selesai, AF-16). Ia hanya memadam baris released terminal dalam kelompok terhad; keadaan hidup tidak pernah disentuh.
  • Suis pemadaman global YABANIN_RESERVATIONS=off menghentikan tempahan baharu (pengapitan mod, §9); peruntukan sedia ada disalirkan melalui reconcile.