Метриканын архитектурасы

Метриканын архитектурасы - бул эрежелердин, артефакттардын жана кызматтардын системасы, алар бир маанидеги аныктамаларды, кайталануучу эсептөөлөрдү, ачык-айкын жеткиликтүүлүктү жана бүткүл уюм боюнча көрсөткүчтөрдү ишенимдүү пайдаланууну камсыз кылат. Максаты - "МАУ", "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/инкременталдык жүктөө, дедуп, убакыт зоналарын бириктирүү.
Data Model (DWH): жылдыз/кар бүртүкчөсү, жай өзгөрүп өлчөө (SCD), суррогат ачкычтар.
Метриканын семантикалык катмары: бирдиктүү аныктамалар, агрегациялар, чыпкалар, убакыт сызыгы, роллап-логика.
Эсептөө катмары: батч/микробатч/агым; терезелер, суу белгилери, ачкычтар боюнча дедуп.
Каталог жана сөздүк: "паспорт метрика", lineage, ээлери, укуктар.
Access жана керектөө: BI/dashboard, API метрик, жүктөө, эксперименттер/AV.

3) Маалыматтар жана метрика келишимдери

Булак келишими (окуялар/таблицалар)

Схема: талаалар, түрлөрү, нөлдүк, негизги ачкыч.
SLA: сергектик (мисалы, "≤ 10 мүнөт лаг"), жыштык, максималдуу кечигип келүү.
Сапаты: ачкычтын уникалдуулугу, жол берилген баалуулуктар домендери, timezone, ыктымалдуулук.
Өзгөртүүлөр: Development схемасы саясаты (backward/forward), deprecation-план.

Метрика келишими

Аты-жөнү/коду: 'RET _ D30 _ v2'

Домен/ээси: Product Analytics

Аныктама (адам тили)

Formula: SQL/Pseudo Code + кирүү терезелер/семантикалык объектилер

Гранулдуулук/убакыт логикасы: day/week; point-in-time эрежелери, timezone

Демейки сегменттер/чыпкалар

Бирдиктер жана валюталар (конверсия курсу/датасы)

SLO: жаңылык ≤ X, тактык ≥ Y, жеткиликтүүлүк ≥ Z

Версия/өзгөртүү тарыхы/кирүү датасы

Guardrails: жол диапазондору, p1/p99 winzorization эрежелери

4) Семантикалык метр катмары

Катмардын милдети - аныктамаларды жана агрегациялоо эрежелерин борборлоштуруп сактоо:

Элементтер: өлчөө (date, country, платформа), фактылар (events, revenue), метрика (ARPU, Retention D30), эсептелүүчү талаалар, календар (кул/дем алыш, майрам).
Убакыт жүрүм-туруму: календардык таблицалар, лагдар, когорттор, "жылма" терезелер (7/30/90).
Rollap жана консистенттүүлүк: күндөр боюнча сумма = ай, ошол эле учурда кош эсепке алып салуу (distinct users).
Mix-adjustment: чынчыл YoY үчүн туруктуу аралаш каналдар/өлкөлөр боюнча нормалдаштыруу.
Мультивалюталар/таймзондор: транзакция күнү базалык валютага алып келүү; жергиликтүү жана "канондук" UTC тилкелери.

5) эсептөө: батч, микробатч, агым

Батч: түнкү/сааттык джоб, толук/инкременталдык кайра эсептөөлөр, демпотенттикти көзөмөлдөө.
Mikrobatch: терезелер 1-15 мүнөт үчүн оперативдүү дашборддор.
Агым: шина аркылуу окуялар; терезелер (tumbling/sliding/session), суу белгилерин (late data), exactly-once семантика (ачкыч боюнча дедуп + offset store).

Терезе үлгүлөрү:

Ыкчам KPI үчүн 'HOP 5m, WINDOW 1h';
Күндүзгү метриктер үчүн 'TUMBLE 1d';
'SESSION 30m' сессиялар үчүн.

6) Сапаты жана текшерүү жөндөмдүүлүгү

Маалымат тесттери: схемалык, домендик (диапазондор), референциалдык байланыштар.
Метрикалык тесттер: инварианттар (DAU ≤ MAU), бош эмес сегменттер, монотондук күтүүлөр (кумулятивдүү).
Текшерүүлөр (reconciliation): семантикалык катмар менен референттик отчеттордун/бухгалтериянын ортосунда.
Data health: сергектик, completeness, кайталоо, NULL үлүшү, анормалдуу секирик.
Drift Metrics: 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).
Анти-дубли: ID эрежелери (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/семантикалык катмар үчүн.
Alerty: 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`.
Саясатчылар: лимиттер, кэш, пагинация, демпотенттик "экспорт".
Version: 'X-Metric-Version: v2' аталышы, deprecation жөнүндө эскертүү.

14) Шаблондор жана экспонаттар

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

Код/версия: 'ARPPU _ v3'

Аныктама: мезгил ичинде төлөөчү колдонуучуга орточо киреше

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

Гранулдуулук: күн; rollup: жума/ай = алуучунун суммасы/туунду суммасы

Sources: '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 жашыруун
Dashboard/эксперименттер эски нускасын алмаштырылган
Changelog/байланыш жөнөтүлдү

SQL-psevdocode-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-таблица.
Колдонуучулардын кош эсеби: Rollab эрежелери жана уникалдуу ачкычтары.
Тунук эмес сергектик: так артта/тактоо убактысын көрсөтүү.
Бир инженерге көз карандылык: баары - код сыяктуу, ревю жана онколл менен.

Жыйынтык

Метриканын архитектурасы - сөздүк + семантикалык катмар + ишенимдүү эсептөө + говернанс жана SLO. Айтылган принциптерди (контракттар, тесттер, версиялар, байкоо, коопсуздук) сактоо менен сиз метриканы "сандар жөнүндө талаш-тартыштардан" өнүмдү жана бизнести башкаруунун туруктуу механизмине айландырасыз.

Метриканын архитектурасы