ADR-005: Собственный bStats-аналог для Indexium Analytics

Дата: 2026-09-06 Статус: Принято (дизайн) / К реализации в Phase 3

Контекст

Скачивания накручиваются CI, нужна честная метрика популярности — активные установки в рантайме. bStats де-факто стандарт для Minecraft модов: lightweight SDK → POST gzip JSON → агрегация. Пользователь предложил полный дизайн с server_uuid, daily_salt, mod_telemetry_pings + mod_daily_stats, opt-out и сортировкой active_servers.

Решение

SDK: MIT Java/Kotlin модуль dev.indexium:analytics ~15KB, IndexiumMetrics(slug) + SimplePie, уважает -Dindexium.analytics.disable=true и config/indexium.json.
Ingestion: POST /api/v1/analytics/submit (gzip, без IP логов) → валидация allow-list → server_hash = sha256(uuid + daily_salt) → Redis 1/15мин → mod_telemetry_pings (TTL 30d).
Storage: Postgres mod_telemetry_pings + mod_daily_stats (breakdown_json) + analytics_salts. Кроном COUNT(DISTINCT server_hash) раз в час. Хватает до 10M пингов/мес, далее TimescaleDB hypertable без смены схемы.
Serving: GET /mods/:slug/analytics?range=7d|30d|90d (кэш 5м), GET /badges/:slug/servers.svg, GET /mods?sort=active_servers.
Приватность: не храним IP, daily_salt ротация (не трекать сквозь дни), custom_charts ≤5 ключей, opt-out на клиенте.

Альтернативы

Сторонний bStats.org — отклонён (внешняя зависимость, нет контроля, нет breakdown по нашим лоадерам).
ClickHouse сразу — отклонён (оверхед для MVP, Postgres хватает).
Хранить сырые пинги навсегда — отклонён (раздувание, достаточно daily агрегата).

Последствия

Плюс: честная сортировка active_servers, графики для авторов, бейджи, без сторонних сервисов.
Минус: +2 таблицы, крон-агрегация, SDK нужно публиковать в Maven Central.
План: сначала Axum handler + агрегация, потом SDK (или наоборот — можно параллельно).

Ссылки

docs/analytics.md
docs/api-spec.md §Analytics
docs/database-schema.md §3

2.7 KiB Raw Blame History Unescape Escape