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

Метрикалардың архитектурасы - бұл бір мәнді анықтамаларды, қайта жасалатын есептеулерді, ашық қолжетімділікті және бүкіл ұйымда көрсеткіштерді сенімді пайдалануды қамтамасыз ететін ережелер, артефактілер мен сервистер жүйесі. Мақсаты - «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).

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

Жедел KPI үшін 'HOP 5m, WINDOW 1h';
күндізгі метриктер үшін '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. Сипатталған қағидаттарды (келісімшарттар, тестілер, нұсқалар, бақылаушылық, қауіпсіздік) сақтай отырып, сіз метриканы «сандар туралы даулардан» өнім мен бизнесті басқарудың тұрақты тетігіне айналдырасыз.

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