Initial commit of Descrybe v2 without local scratch artifacts.

Drop one-shot tmp/axe scripts and agent i18n scratch so the Gitea tree is deployable.
2026-08-09 22:47:43 +02:00
commit 8580c996c3
1285 changed files with 325780 additions and 0 deletions
@@ -0,0 +1,32 @@
+# Prometheus examples (Descrybe v2)
+
+Starter scrape + alert configs for gated `GET /metrics` and `/readyz` worker freshness.
+**Examples only** — not a live Prometheus install. No secrets; replace placeholder hosts with private/mesh targets.
+
+| File | Purpose |
+|------|---------|
+| [`scrape.example.yml`](scrape.example.yml) | Job snippets: `descrybe-api`, `descrybe-worker`, blackbox `/readyz` |
+| [`alerts.example.yml`](alerts.example.yml) | RED + sync + scrape-down + worker readiness rules |
+
+Canonical guidance: [docs/production-readiness.md — Ops: Prometheus scrape](../../docs/production-readiness.md#ops-prometheus-scrape).
+Cutover checklist: [docs/production-checklist.md §1d](../../docs/production-checklist.md#1d-metrics-scrape--alerts-cutover).
+
+## Topology (summary)
+
+```
+Prometheus ──scrape──► API  HTTP_ADDR       GET /metrics  → HTTP RED series
+           ──scrape──► Worker METRICS_ADDR  GET /metrics  → sync_* series
+           ──probe───► API  HTTP_ADDR       GET /readyz   → worker freshness (HTTP 200)
+Public VIP ──deny────► /metrics
+```
+
+- Production Gate: loopback (or `METRICS_PUBLIC=1` on a **private** VIP only).
+- Worker sync series require `METRICS_ADDR` (e.g. `127.0.0.1:9091`).
+- Heartbeat age is **not** a Prom series. `/readyz` returns **503** when `checks.worker` is `missing`/`stale` (stale after **60s**). On-call triage: JSON `worker_last_seen_age_s` + `checks.worker`.
+
+## Status (cutover blocker #9)
+
+| Layer | Status |
+|-------|--------|
+| Code + example scrape/alert files | **CODE DONE** |
+| Live scrape targets + alertmanager routing on the host | **OPS OPEN** |