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

Архітектура метрик - це система правил, артефактів і сервісів, що забезпечують однозначні визначення, відтворюваний розрахунок, прозорий доступ і надійну експлуатацію показників у всій організації. Мета - щоб «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 метрик, вивантаження, експерименти/АВ.

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. Дотримуючись описаних принципів (контракти, тести, версії, спостережуваність, безпека), ви перетворюєте метрики з «суперечок про цифри» в стійкий механізм управління продуктом і бізнесом.

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