rf4-spotter/docs/observability.md

Минимальная 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.