ik/rf4-spotter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: define alpha observability baseline

Browse Source
This commit is contained in:
ik
2026-09-13 09:32:22 +07:00
parent 016d459861
commit aae5e0926a
3 changed files with 43 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/observability.md
+40
View File
@@ -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).