From aae5e0926ab5b69275ea1e172a523e31bfaff9a8 Mon Sep 17 00:00:00 2001 From: IK Date: Sun, 13 Sep 2026 09:32:22 +0700 Subject: [PATCH] docs: define alpha observability baseline --- README.md | 2 ++ docs/ROADMAP.md | 2 +- docs/observability.md | 40 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 docs/observability.md diff --git a/README.md b/README.md index 474b8a8..45cf3e0 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,8 @@ Production-контур для домена `rf4spotter.ru`, TLS, секреты Host-side мониторинг контейнеров, readiness, диска, объёма PostgreSQL/MinIO, резервных копий и TLS описан в [`docs/production-monitoring.md`](docs/production-monitoring.md). +Минимальные SLI открытой альфы, стартовые пороги и правила безопасной телеметрии собраны в [observability plan](docs/observability.md). До выбора сервера используются существующие JSON-логи, readiness, diagnostics и host monitor; отдельный metrics-стек заранее не добавляется. + Принятые границы стека, memory-cache, scheduler и хранилищ зафиксированы в [архитектурных решениях](docs/architecture-decisions.md). Порядок действий при заполнении диска, отказах PostgreSQL/MinIO, зависшем импорте, ошибке миграции и утечке секрета находится в [incident runbook](docs/incident-runbook.md). Ежедневный systemd timer создаёт проверяемую копию до retention-очистки, а production Compose ограничивает рост JSON-логов контейнеров. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index f8f1209..d9e750a 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -58,7 +58,7 @@ - [x] **Q15 · Частичная деградация главной.** SSR независимо получает activity, community signals и оба справочника через settled-результаты. Отказ секции показывает собственный `StatePanel`, сохраняет остальные данные и HTTP 200 с `X-RF4-Partial`/`Cache-Control: no-store`; только отказ всех четырёх частей возвращает 503, `Retry-After` и noindex. Client-side loading и optimistic UI не добавлялись. - [x] **Q16 · Контракт OpenAPI.** `apps/api/openapi.json` детерминированно генерируется из FastAPI; CI проверяет его актуальность после backend suite. Изменение artifact обязательно рассматривается вместе с реализацией, а ручное редактирование не используется. - [x] **Q17 · Эксплуатационные документы.** Зафиксированы ADR по Astro/FastAPI/PostgreSQL, локальному cache, scheduler/cooldown и разделению PostgreSQL/MinIO. Incident runbook покрывает заполнение диска, отказ PostgreSQL/MinIO, зависшие импорты, ошибки миграций, компрометацию секретов и критерии закрытия без опасных reset/recreate операций. -- [ ] **Q18 · Минимальная observability.** До открытой альфы определить дешёвые метрики request count/latency/error rate, глубины moderation/staging и возраста последнего успешного импорта. Формат и exporter выбрать после выбора мониторинга сервера; полноценный tracing не внедрять без подтверждённой потребности. +- [x] **Q18 · Минимальная observability.** Зафиксированы дешёвые SLI, стартовые пороги и источники для request count/latency/5xx, moderation/staging depth, возраста импортов и инфраструктуры. Начальный контур использует JSON-логи, readiness, diagnostics и host monitor; exporter выбирается после покупки сервера, tracing и Prometheus не вводятся без измеренной потребности. Перед альфой остаётся подключить реальный канал и проверить critical/recovery alert. ### Административная панель diff --git a/docs/observability.md b/docs/observability.md new file mode 100644 index 0000000..af9a73f --- /dev/null +++ b/docs/observability.md @@ -0,0 +1,40 @@ +# Минимальная observability открытой альфы + +До выбора сервера RF4 Spotter не добавляет Prometheus, Grafana, tracing или отдельную БД метрик. Начальный контур использует уже существующие структурированные JSON-логи API/scheduler, `/health`, `/ready`, защищённый diagnostics и `deploy/monitor.sh`. Это снижает эксплуатационную стоимость и не создаёт ложной уверенности от непроверенного exporter. + +## Обязательные сигналы + +| Сигнал | Источник | Начальный порог | Реакция | +|---|---|---|---| +| HTTP request count | JSON-событие `request completed`, по method/path/status | отсутствие запросов само по себе не авария | сравнить с доступностью proxy и DNS | +| HTTP error rate | те же события, доля 5xx за 5 минут | warning > 2%, critical > 5% при ≥20 запросах | проверить request ID, API/DB/MinIO | +| HTTP latency | `duration_ms`, p50/p95 за 5 минут | warning p95 > 750 мс, critical > 2 с при ≥20 запросах | отделить DB-запросы от внешних зависимостей | +| Moderation queue | diagnostics: `catch_reports.pending` | warning > 50 или старейшая запись > 24 ч | увеличить окно модерации, проверить уведомления | +| Staging queue | diagnostics: `external_observations` staged/mapped/ready | warning > 500 или устойчивый рост 24 ч | проверить aliases, полноту и импорт | +| Возраст импорта | `/ready` community sources и `/api/v1/source-status` | warning > 2 интервалов; critical согласно required source | проверить cooldown/backoff и DOM-контракт | +| Контейнеры/диск/DB/MinIO/backup/TLS | `deploy/monitor.sh` | пороги `.env.production` | действовать по incident runbook | + +Порог является стартовым и меняется только после недели полевых данных. Низкий трафик не должен превращать единичный 5xx в ложную аварию, поэтому rate/latency оцениваются только при минимальном числе запросов. + +## Безопасность телеметрии + +- не собирать IP, Authorization, cookies, query string, имена игроков и parser payload; +- связывать ошибку только по случайному `request_id`; +- admin diagnostics не передавать внешнему сервису и получать только через оба защитных барьера; +- хранить подробные application logs 14 дней, агрегаты — до 90 дней; доступ ограничить владельцем сервера; +- URL источника и свободный текст причины модерации не использовать как label метрики. + +## Выбор exporter после покупки сервера + +1. Если провайдер уже даёт сбор journald/container logs и uptime checks — использовать его. +2. Иначе подключить лёгкий host-agent, который читает stdout контейнеров и результат systemd monitor; не выдавать внутренний `/metrics` наружу. +3. Полноценный Prometheus вводить только при необходимости исторических p95 и нескольких хостах. Tracing — только после доказанного межсервисного bottleneck. +4. До приглашения игроков проверить доставку тестового critical-сигнала, recovery-сигнала и отсутствие секретов в уведомлении. + +## Альфа-приёмка + +- внешний probe проверяет `/health`, а отдельный — `/ready`; +- failed systemd unit доставляет результат `deploy/monitor.sh` в реальный канал; +- dashboard показывает request rate, 5xx rate, p95, две глубины очередей и возраст каждого импорта; +- уведомления группируются минимум на 10 минут и имеют recovery-событие; +- ссылка из alert ведёт в этот документ и [incident runbook](incident-runbook.md).