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, komponenbudget-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, komponenbudget-admission) — hasil geran/kemasukan, kependaman tambahan dan pelanggaran batas (§4.2).
1. Rujukan metrik (§7.2)
| Siri | Jenis | Pengeluar | Maksud |
|---|---|---|---|
budget_reserved_micro_usd{scope_kind} | tolok | reconcile | Kapasiti yang dibekukan oleh tempahan bagi setiap skop keras (wallet/team_month/agent_day/session). |
budget_allowance_released_total{reason} | kaunter | reconcile | Pelepasan: 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} | tolok | reconcile | Pelanggaran §7.1.3: Σ|reserved(row) − Σ baki elaun belum dilepaskan bagi baris itu|. Laluan yang memelihara wang mengekalkan ini pada 0. |
budget_wallet_headroom_micro_usd | tolok | reconcile | LHS kes terburuk §7.1.4 merentas organisasi: min(balance − remainder − floor − reserved). |
budget_wallet_invariant_violations | tolok | reconcile | Kiraan organisasi dengan ruang kepala §7.1.4 negatif (organisasi dinamakan dalam log loggerd, tidak pernah dalam label). |
budget_stranded_micro_usd | tolok | reconcile | Kapasiti yang dibekukan oleh elaun belum dilepaskan yang luput (§12): replika mati menyekat wang sehingga 2 jam + TTL. |
settlement_lag_seconds | tolok | reconcile | Umur kerja penyelesaian tertua yang belum diselesaikan (pending/retry/processing). |
budget_grants_total{scope_kind,result} | kaunter | gerbang | granted / insufficient / no_source / error (gangguan stor). |
budget_grant_duration_seconds | histogram | gerbang | Kependaman geran PG. |
budget_local_admit_total{result} | kaunter | gerbang | Cara Reserve membiayai permintaan: local / grant / refused. |
budget_admission_overhead_seconds | histogram | gerbang | Kependaman kemasukan segerak yang ditambah oleh lapisan (Plan + Reserve). Pintu D17: p95 ≤ 5 ms. |
budget_bound_violation_total{scope_kind} | kaunter | gerbang | Permintaan yang dimuktamadkan dengan actual > bound (§4.2) — satu-satunya sumber terlebih belanja yang sah. |
budget_bound_overshoot_micro_usd_total{scope_kind} | kaunter | gerbang | Terkumpul (actual − bound)+ dalam µUSD. |
gateway_reservations_would_deny_total{scope_kind} | kaunter | gerbang (NEXT-18c) | budget_would_deny_total ADR: penolakan yang diperhatikan dalam bayang (input laporan keluar D17). |
gateway_reservations_denied_total{scope_kind} | kaunter | gerbang (NEXT-18c) | Penolakan yang dikenakan dalam enforce (402/429/403). |
gateway_would_bill_partial_micro_usd_total{scope_kind} | kaunter | penyelesaian (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} | kaunter | penyelesaian (NEXT-18d) | Batas terpelihara peristiwa penggunaan tidak diketahui — tidak pernah dibilkan, kelihatan di sini. |
gateway_settlement_batch_size | histogram | penyelesaian (NEXT-18d) | Kerja bagi setiap TX penyelesaian kelompok organisasi. |
gateway_settlement_jobs_backlog{state} | tolok | penyelesaian (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:
sum(increase(budget_bound_violation_total[7d])) / sum(increase(budget_local_admit_total{result=~"local|grant"}[7d]))≤ 0.001;- terlebih terkumpul
increase(budget_bound_overshoot_micro_usd_total[7d])≤|grace_floor|organisasi (nilai per organisasi melalui API pentadbir); - p95
budget_admission_overhead_seconds≤ 0.005; gateway_reservations_would_deny_totaldangateway_would_bill_partial_micro_usd_totaldipecahkan 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
releasedlalai kepada 90 hari (ufuk yang sama seperti pengekalan kerja penyelesaian yang telah selesai, AF-16). Ia hanya memadam barisreleasedterminal dalam kelompok terhad; keadaan hidup tidak pernah disentuh. - Suis pemadaman global
YABANIN_RESERVATIONS=offmenghentikan tempahan baharu (pengapitan mod, §9); peruntukan sedia ada disalirkan melalui reconcile.