Архитектура метрик

Архитектура метрик — это система правил, артефактов и сервисов, обеспечивающих однозначные определения, воспроизводимый расчет, прозрачный доступ и надежную эксплуатацию показателей во всей организации. Цель — чтобы «MAU», «Retention D30» или «ARPPU» считались одинаково во всех дашбордах, экспериментах и отчетах.

1) Принципы

1. Единый источник истины (Single Source of Truth) для формул и справочников.
2. Отделение семантики от реализации: бизнес-определение живет в семантическом слое, а не в каждом SQL/ноутбуке.
3. Версионирование метрик, схем и формул (v1→v2) с управляемой миграцией истории.
4. Воспроизводимость и тестируемость: расчеты детерминированы, покрыты тестами.
5. Наблюдаемость: свежесть, полнота, консистентность и дрейф — с SLO и алертами.
6. Безопасность и приватность: минимизация PII, RLS/CLS, аудит.
7. Операционка как код: определения, трансформации, политики — в репозитории с CI/CD.

2) Слои архитектуры

Исходные данные: события/транзакции, справочники, логи моделей/инфры.
Интеграция и очистка: CDC/инкрементальная загрузка, дедуп, унификация временных зон.
Модель данных (DWH): звезда/снежинка, медленно изменяющиеся измерения (SCD), суррогатные ключи.
Семантический слой метрик: единые определения, агрегации, фильтры, time grain, роллап-логика.
Расчетный слой: батч/микробатч/стрим; окна, водяные метки, дедуп по ключам.
Каталог и словарь: «паспорт метрики», lineage, владельцы, права.
Доступ и потребление: BI/дашборды, API метрик, выгрузки, эксперименты/AB.

3) Контракты данных и метрик

Контракт источника (событий/таблицы)

Схема: поля, типы, нуллабельность, первичный ключ.
SLA: свежесть (например, «≤10 минут лаг»), частота, максимальный задержанный приход.
Качество: уникальность ключа, допустимые домены значений, timezone, идемпотентность.
Изменения: политика эволюции схемы (backward/forward), deprecation-план.

Контракт метрики

Имя/код: `RET_D30_v2`

Домейн/владелец: Product Analytics

Определение (человеческим языком)

Формула: SQL/псевдокод + входные витрины/семантические объекты

Гранулярность/временная логика: day/week; point-in-time правила, timezone

Сегменты/фильтры по умолчанию

Единицы и валюты (курс/дата конверсии)

SLO: свежесть ≤ X, точность ≥ Y, доступность ≥ Z

Версия/история изменений/дата вступления

Guardrails: допустимые диапазоны, правила винзоризации p1/p99

4) Семантический слой метрик

Задача слоя — централизованно хранить определения и правила агрегации:

Элементы: измерения (date, country, platform), факты (events, revenue), метрики (ARPU, Retention D30), вычисляемые поля, календарь (раб/выходные, праздники).
Поведение времени: календарные таблицы, лаги, когорты, «скользящие» окна (7/30/90).
Роллап и консистентность: сумма по дням = месяц, при этом исключать двойной учет (distinct users).
Mix-adjustment: нормализация под постоянный микс каналов/стран для честного YoY.
Мультивалюта/таймзоны: приведение к базовой валюте на дату транзакции; локальный и «канонический» UTC-срезы.

5) Расчет: батч, микробатч, стрим

Батч: ночные/почасовые джобы, полные/инкрементальные пересчеты, контроль идемпотентности.
Микробатч: окна 1–15 минут для оперативных дашбордов.
Стрим: события через шину; окна (tumbling/sliding/session), водяные метки (late data), exactly-once семантика (дедуп по ключу + offset store).

Паттерны окон:

`HOP 5m, WINDOW 1h` для оперативных KPI;
`TUMBLE 1d` для дневных метрик;
`SESSION 30m` для сессий.

6) Качество и проверяемость

Тесты данных: схематические, доменные (диапазоны), референциальные связи.
Тесты метрик: инварианты (DAU≤MAU), непустые сегменты, ожидания монотонности (кумулятивы).
Сверки (reconciliation): между семантическим слоем и референс-отчетами/бухгалтерией.
Data health: свежесть, completeness, дубликаты, доля NULL, аномальные скачки.
Метрики дрейфа: PSI/KL/JS на ключевых фичах, особенно для ML-метрик.

7) Версионирование и миграции

Версия формулы: `METRIC_NAME_vN`. Запрещено «тихо» менять определение без смены версии.

Стратегии миграции:

Side-by-side: v1 и v2 считаются параллельно; проводится сверка и обучение пользователей.
Cut-over: переключение потребителей на v2 в окне низкой нагрузки; архив v1.
Пересчет истории: backfill по историческим данным; протокол разницы (diff-отчет).
Коммуникации: changelog, дата вступления, кого затронет, инструкции.

8) Модель данных для метрик

Факты: зерно (event_id, transaction_id, user_day), время события, сумма/величины.
Измерения: пользователь, устройство, география, канал, продукт, календарь; SCD-тип для историчности.
Ключи: суррогатные ID, стабильные бизнес-ключи, таблицы соответствий (mapping).
Анти-дубли: правила идентичности (user merge), окна «склейки» сессий.

9) Единицы, валюты, сезонность

Единицы/формат: явные единицы измерения, округления, шкалы (лог/линейная).
Мультивалюта: конверсия по курсу на дату операции; хранить и «сырую», и нормализованную сумму.
Сезонность: YoY и сезонные индексы; отдельные «праздничные» эффекты.

10) Безопасность и доступ

Row-Level Security (RLS): доступ к метрикам в разрезе страны/бренда/партнера.
Column-Level Security (CLS): маскирование PII/финансовых полей.
Аудит: кто запрашивал метрику, какие фильтры, какие экспортировал данные.
Дифференциация API: «агрегаты по ролям» vs «детализированные выгрузки».

11) Наблюдаемость и SLO

SLO свежести: напр., «оперативные KPI — лаг ≤ 15 мин, ежедневные — до 06:00 локального времени».
SLO доступности: ≥ 99.9% для API/семантического слоя.
Алерты: просрочка SLO, скачки метрик, рост NULL/дубликатов, расхождение v1 vs v2 > X%.
Runbooks: что делать при деградации — шаги RCA, fallback (например, переключение на последнюю валидную «снепшот-метрику»).

12) Эксперименты и метрики

Guardrail-метрики: латентность, отказоустойчивость, FPR/FNR для скорингов.
Единые определения для A/B: конверсии, удержание, NSM — через тот же семантический слой.
Минимально различимый эффект (MDE), power-анализ: хранить параметры в карточке метрики.
Каузальная атрибуция: политики по mix-adjustment и контрольным группам.

13) API метрик и потребление

Запросы: `GET /metrics/{name}?from=2025-09-01&to=2025-10-01&dims=country,platform&filters=channel:paid`.
Политики: лимиты, кэш, пагинация, идемпотентные «экспорты».
Версии: заголовок `X-Metric-Version: v2`, предупреждения о deprecation.

14) Шаблоны и артефакты

Паспорт метрики (пример)

Код/версия: `ARPPU_v3`

Определение: средняя выручка на платящего пользователя за период

Формула: `sum(revenue_net) / count_distinct(user_id where paying_flag=1)`

Гранулярность: день; rollup: неделя/месяц = сумма числителя / сумма знаменателя

Источники: `fact_payments_v2`, `dim_users_scd`

Единицы: валюта `base_ccy`; конверсия по курсу на дату

Фильтры по умолчанию: активные рынки, исключить тестовые транзакции

SLO: свежесть ≤ 1 ч; доступность API ≥ 99.9%

Guardrails: ARPPU ∈ [0; 10 000]; винзоризация p1/p99

Владельцы: Monetization Analytics; дата ревизии: 2025-10-01

Check-list релиза метрики

Определение и формула согласованы, покрыты тестами
Семантический объект создан; lineage задокументирован
Backfill и сверки с референсом завершены
SLO/алерты настроены; runbook готов
Права и RLS настроены; PII скрыта
В дашбордах/экспериментах заменены старые версии
Changelog/коммуникация отправлены

SQL-псевдокод point-in-time (пример Retention D30)

sql
WITH cohort AS (
SELECT user_id, MIN(event_date) AS signup_date
FROM fact_events
WHERE event_type = 'signup'
GROUP BY 1
),
activity AS (
SELECT user_id, event_date
FROM fact_events
WHERE event_type = 'app_open'
),
ret AS (
SELECT c. signup_date,
COUNT(DISTINCT CASE WHEN a. event_date = c. signup_date + INTERVAL '30 day' THEN a. user_id END) AS returned,
COUNT(DISTINCT c. user_id) AS cohort_size
FROM cohort c
LEFT JOIN activity a
ON a. user_id = c. user_id
AND a. event_date BETWEEN c. signup_date AND c. signup_date + INTERVAL '30 day'
GROUP BY 1
)
SELECT signup_date, returned / cohort_size AS retention_d30
FROM ret;

15) Частые ошибки и как их избежать

Тихие правки формул: всегда через версию и changelog.
Метрики «в каждом ноутбуке по-разному»: принуждайте к семантическому слою/API.
Несогласованные таймзоны/валюты: централизованный календарь и FX-таблица.
Двойной учет пользователей: роллап-правила и уникальные ключи.
Непрозрачная свежесть: явно показывайте лаг/время обновления.
Зависимость от одного инженера: все — как код, с ревью и онколлом.

Итог

Архитектура метрик — это словарь + семантический слой + надежный расчет + говернанс и SLO. Следуя описанным принципам (контракты, тесты, версии, наблюдаемость, безопасность), вы превращаете метрики из «споров о цифрах» в устойчивый механизм управления продуктом и бизнесом.

Архитектура метрик