docs: define alpha observability baseline
This commit is contained in:
@@ -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-логов контейнеров.
|
||||
|
||||
|
||||
+1
-1
@@ -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.
|
||||
|
||||
### Административная панель
|
||||
|
||||
|
||||
@@ -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).
|
||||
Reference in New Issue
Block a user