29 lines
2.7 KiB
Markdown
29 lines
2.7 KiB
Markdown
# 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
|