Metrik memarlıq

Metrika arxitekturası bütün təşkilatda birmənalı təriflər, təkrar hesablamalar, şəffaf giriş və göstəricilərin etibarlı istismarını təmin edən qaydalar, artefaktlar və xidmətlər sistemidir. Məqsəd bütün daşbordlarda, təcrübələrdə və hesabatlarda «MAU», «Retention D30» və ya «ARPPU» eyni hesab edilməsidir.

1) Prinsiplər

1. Formula və kataloqlar üçün vahid həqiqət mənbəyi (Single Source of Truth).
2. Semantikanın həyata keçirilməsindən ayrılması: biznes tərifi hər bir SQL/noutbukda deyil, semantik təbəqədə yaşayır.
3. Metriklərin, sxemlərin və düsturların (v1 → v2) idarə olunan tarix miqrasiyası ilə versiyası.
4. Reproduktivlik və sınaq qabiliyyəti: hesablamalar determinizə edilmiş, testlərlə örtülmüşdür.
5. Müşahidə: təzəlik, dolğunluq, tutarlılıq və sürüklənmə - SLO və alertlərlə.
6. Təhlükəsizlik və məxfilik: PII, RLS/CLS, auditin minimuma endirilməsi.
7. Kod kimi əməliyyat: təriflər, transformasiyalar, siyasətlər - CI/CD ilə anbarda.

2) Memarlıq təbəqələri

Mənbə məlumatları: hadisələr/əməliyyatlar, kataloqlar, model qeydləri/infra.
İnteqrasiya və təmizləmə: CDC/inkremental yükləmə, dedup, vaxt zonalarının unifikasiyası.
Data Model (DWH): ulduz/qar dənəsi, yavaş dəyişən ölçü (SCD), surroqat açarları.
Metriklərin semantik təbəqəsi: vahid təriflər, aqreqasiyalar, filtrlər, vaxt həddi, rollap-məntiq.
Hesablama qatı: batch/mikrobatch/axın; pəncərələr, su işarələri, açar dedup.
Kataloq və lüğət: «pasport metrikası», lineage, sahibləri, hüquqları.
Giriş və istehlak: BI/dashboard, API metrik, boşaltma, təcrübələr/AV.

3) Məlumat və metrik müqavilələr

Mənbə müqaviləsi (hadisələr/cədvəllər)

Sxem: sahələr, tiplər, sıfır qabiliyyət, əsas açar.
SLA: təzəlik (məsələn, «≤ 10 dəqiqə laq»), tezlik, maksimum gecikmiş gəliş.
Keyfiyyət: açarın unikallığı, icazə verilən dəyər domenləri, timezone, idempotentlik.
Dəyişikliklər: sxemin təkamül siyasəti (backward/forward), deprecation planı.

Metrika müqaviləsi

Adı/kodu: 'RET _ D30 _ v2'

Domain/Sahibi: Product Analytics

Tərif (insan dili)

Formula: SQL/psevdocode + giriş vitrinləri/semantik obyektlər

Qranulyarlıq/vaxt məntiqi: day/week; point-in-time qaydaları, timezone

Seqmentlər/filtrlər

Vahidlər və valyutalar (məzənnə/dönüşüm tarixi)

SLO: təzəlik ≤ X, dəqiqlik ≥ Y, mövcudluq ≥ Z

Versiyası/dəyişiklik tarixi/giriş tarixi

Guardrails: icazə verilən diapazonlar, p1/p99 şərab qaydaları

4) Metrik semantik təbəqə

Təbəqənin vəzifəsi - mərkəzləşdirilmiş qaydaları və aqreqasiya qaydalarını saxlamaqdır:

Elementlər: ölçmə (date, country, platforma), faktlar (events, revenue), metriklər (ARPU, Retention D30), hesablanan sahələr, təqvim (qul/həftə sonu, tətil).
Zaman davranışı: təqvim cədvəlləri, lağlar, kohortlar, «sürüşmə» pəncərələri (7/30/90).
Rollap və tutarlılıq: gün üzrə məbləğ = ay, ikiqat uçot istisna (distinct users).
Mix-adjustment: ədalətli YoY üçün kanal/ölkələrin daimi qarışığı altında normallaşdırma.
Multivalyuta/taymzonlar: əməliyyat tarixinə baza valyutasına gətirilməsi; yerli və «kanonik» UTC dilimləri.

5) Hesablama: batch, mikrobatch, axın

Batch: gecə/saatlıq joblar, tam/inkremental yenidən hesablamalar, idempotentlik nəzarəti.
Mikrobatch: pəncərələr əməliyyat dashboard üçün 1-15 dəqiqə.
Axın: şin vasitəsilə hadisələr; pəncərələr (tumbling/sliding/session), su etiketləri (late data), exactly-once semantika (açar dedup + offset store).

Pəncərə nümunələri:

Əməliyyat KPI üçün 'HOP 5m, WINDOW 1h';
Gündəlik metrlər üçün 'TUMBLE 1d';
Sessiyalar üçün 'SESSION 30m'.

6) Keyfiyyət və yoxlanılabilirlik

Məlumat testləri: sxematik, domen (diapazonlar), referensial əlaqələr.
Metrik testlər: invariantlar (DAU ≤ MAU), boş seqmentlər, monotonluq gözləntiləri (məcmu).
Relations (reconciliation): semantik təbəqə və referans hesabatları/mühasibat arasında.
Data health: təravət, completeness, dublikatlar, NULL payı, anormal sıçrayışlar.
Sürüklənmə metrikləri: PSI/KL/JS əsas fiqurlarda, xüsusilə ML-metriklər üçün.

7) Version və miqrasiya

Formula versiyası: 'METRIC _ NAME _ vN'. Versiyanı dəyişdirmədən tərifi «sakit» dəyişdirmək qadağandır.

Miqrasiya strategiyaları:

Side-by-side: v1 və v2 paralel sayılır; istifadəçilərin müqayisəsi və təlimi aparılır.
Cut-over: aşağı yük pəncərəsində v2 istehlakçı keçid; arxiv v1.
Tarixin yenidən hesablanması: tarixi məlumatlara görə backfill; fərq protokolu (diff-hesabat).
Rabitə: changelog, giriş tarixi, kimə təsir edəcək, təlimat.

8) Metriklər üçün data modeli

Faktlar: taxıl (event_id, transaction_id, user_day), hadisə vaxtı, məbləğ/kəmiyyətlər.
Ölçülər: istifadəçi, cihaz, coğrafiya, kanal, məhsul, təqvim; Tarixilik üçün SCD tipi.
Açarlar: surroqat ID, sabit biznes açarları, uyğunluq cədvəlləri (mapping).
Anti-dubli: kimlik qaydaları (user merge), seansların «yapışdırma» pəncərələri.

9) Vahidlər, valyutalar, mövsümilik

Vahidlər/format: açıq ölçü vahidləri, yuvarlaqlaşdırma, şkalalar (log/xətti).
Multivalyuta: əməliyyat tarixindəki məzənnə üzrə konvertasiya; həm «xam», həm də normallaşdırılmış məbləği saxlamaq.
Mövsümlük: YoY və mövsümi indekslər; ayrı-ayrı «bayram» effektləri.

10) Təhlükəsizlik və giriş

Row-Level Security (RLS): ölkə/marka/tərəfdaş kontekstində metriklərə çıxış.
Column-Level Security (CLS): PII/maliyyə sahələrinin maskalanması.
Audit: Kim metrika tələb etdi, hansı filtrlər, hansı məlumatları ixrac etdi.
API differensiasiyası: «rollar üzrə aqreqatlar» vs «ətraflı boşaltmalar».

11) Müşahidə və SLO

SLO təravəti: məsələn, «operativ KPI - lag ≤ 15 dəq, gündəlik - 06:00 yerli vaxt».
SLO mövcudluğu: ≥ 99. API/semantik təbəqə üçün 9%.
Alertlər: SLO gecikməsi, metrik sıçrayışlar, NULL/dublikat artımı, v1 vs v2> X% fərqi.
Runbooks: deqradasiya zamanı nə etmək - RCA addımları, fallback (məsələn, son valid «snepshot metrika» keçid).

12) Eksperimentlər və metriklər

Guardrail metrikası: gecikmə, pozulma müqaviməti, skoring üçün FPR/FNR.
A/B üçün vahid təriflər: dönüşümlər, saxlama, NSM - eyni semantik təbəqə vasitəsilə.
Minimal fərqlənən effekt (MDE), güc analizi: parametrləri metrik kartda saxlayın.
Kauzal atributlar: mix-adjustment və nəzarət qrupları üzrə siyasətlər.

13) API metrik və istehlak

Запросы: `GET /metrics/{name}?from=2025-09-01&to=2025-10-01&dims=country,platform&filters=channel:paid`.
Siyasətçilər: limitlər, cache, pagination, idempotent «ixrac».
Versiyası: başlıq 'X-Metric-Version: v2', deprecation haqqında xəbərdarlıqlar.

14) Şablonlar və artefaktlar

Metrika pasportu (nümunə)

Kod/versiya: 'ARPPU _ v3'

Tərif: ödəyən istifadəçi üçün orta gəlir

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

Qranulyarlıq: gün; rollup: həftə/ay = ədədin cəmi/məxrəcə cəmi

Mənbələr: 'fact _ payments _ v2', 'dim _ users _ scd'

Vahidlər: valyuta 'base _ ccy'; məzənnə üzrə konvertasiya

Default filtrlər: aktiv bazarlar, test əməliyyatları istisna

SLO: təzəlik ≤ 1 saat; API mövcudluğu ≥ 99. 9%

Guardrails: ARPPU ∈ [0; 10 000]; vinzorization p1/p99

Sahibləri: Monetization Analytics; təftiş tarixi: 2025-10-01

Check-list buraxılış metrikası

Tərif və düstur razılaşdırılmış, testlərlə örtülmüşdür
Semantik obyekt yaradılmışdır; lineage sənədləşdirilmiş
Backfill və istinad ilə müqayisə tamamlandı
SLO/alert özelleştirilmiş; runbook hazır
Hüquqlar və RLS konfiqurasiya; PII gizli
Dashboard/təcrübələr köhnə versiyaları əvəz
Changelog/rabitə göndərilib

SQL-psevdokod point-in-time (Retention D30 nümunəsi)

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) Tez-tez səhvlər və onlardan necə qaçmaq olar

Düsturların sakit düzəlişləri: həmişə versiya və changelog vasitəsilə.
Metriklər «hər noutbukda fərqli»: semantik/API təbəqəsinə məcbur edin.
Razılaşdırılmamış taymzonlar/valyutalar: mərkəzləşdirilmiş təqvim və FX cədvəli.
İkiqat istifadəçi uçotu: rollap qaydaları və unikal açarlar.
Qeyri-şəffaf təravət: açıq-aşkar lag/yeniləmə vaxtı göstərin.
Bir mühəndisdən asılılıq: hər şey - kod kimi, revyu və onkoll ilə.

Yekun

Metrik memarlıq lüğət + semantik təbəqə + etibarlı hesablama + hovernans və SLO. Təsvir olunan prinsiplərə (müqavilələr, testlər, versiyalar, müşahidə, təhlükəsizlik) əməl edərək metrikləri «rəqəmlər haqqında mübahisələrdən» davamlı məhsul və biznes idarəetmə mexanizminə çevirirsiniz.

Metrik memarlıq