Arhitectură metrică

Arhitectură metrică

Arhitectura metrică este un sistem de reguli, artefacte și servicii care oferă definiții lipsite de ambiguitate, calcul reproductibil, acces transparent și funcționarea fiabilă a indicatorilor în întreaga organizație. Scopul este ca „MAU”, „Retention” D30 sau „ARPPU” să fie considerate aceleași în toate tablourile de bord, experimentele și rapoartele.

1) Principii

1. Sursa unică de adevăr pentru formule și cărți de referință.
2. Separarea semanticii de implementare: definiția afacerii trăiește într-un strat semantic, nu în fiecare SQL/laptop.
3. Versioning metrics, scheme și formule (v1→v2) cu migrarea istoriei gestionate.
4. Reproductibilitatea și testabilitatea: calculele sunt deterministe, acoperite de teste.
5. Observabilitate: prospețime, plenitudine, consistență și derivă - cu SLO-uri și alerte.
6. Securitate și confidențialitate: minimizare PII, RLS/CLS, audit.
7. Sistemul de operare ca cod: definiții, transformări, politici - în depozitul cu CI/CD.

2) Straturi de arhitectură

Date sursă: evenimente/tranzacții, cărți de referință, jurnale model/infra.
Integrare și curățare: CDC/incremental loading, dedup, unificarea fusurilor orare.
Modelul de date (DWH): stele/fulg de zăpadă, măsurători care se schimbă lent (SCD), chei surogat.
Strat semantic de metrică: definiții uniforme, agregări, filtre, cereale de timp, logică rollup.
Strat de proiectare: lot/microbatch/flux; ferestre, urme de apă, chei.
Catalog și dicționar: „măsurători de pașaport”, descendență, proprietari, drepturi.
Acces și consum: BI/tablouri de bord, metrici API, încărcări, experimente/AB.

3) Contracte de date și măsurători

Contract sursă (Evenimente/Tabele)

Schema: domenii, tipuri, nulitate, cheie primară.
SLA: prospețime (de exemplu, „≤10 minute lag”), frecvență, sosire maximă întârziată.
Calitate: unicitate cheie, domenii valide, fus orar, idempotenta.
Modificări: politica de evoluție a schemei (înapoi/înainte), planul de abatere.

Contract metric

Nume/ID: 'RET _ D30 _ v2'

Domaine/Proprietar: Analiza produselor

Definiție (în limba umană)

Formula: SQL/pseudocode + storefronturi de intrare/obiecte semantice

Granularitate/logică temporală: zi/săptămână; reguli punctuale, fus orar

Segmente/filtre implicite

Unități și valute (rata de conversie/data)

SLO: prospețime ≤ X, precizie ≥ Y, disponibilitate ≥ Z

Versiune/Schimba istoricul/Data efectivă

Guardrails: intervale valabile, Reguli de Winzorization p1/p99

4) Strat semantic de valori

• Elemente: dimensiuni (data, tara, platforma), fapte (evenimente, venituri), valori (ARPU, retentie D30), campuri calculate, calendar (munca/weekend, sarbatori).
• Comportamentul timpului: tabele calendaristice, lag-uri, cohorte, ferestre „glisante” (7/30/90).
• Rollup și consistență: suma pe zi = lună, excluzând în același timp dubla numărare (utilizatori distincți).
• Mix-ajustare: normalizare la un amestec constant de canale/țări pentru YoY onest.
• Multicurrency/fusones: ajustat la moneda de bază la data tranzacției; felii UTC locale și „canonice”.

5) Calcul: lot, microbatch, flux

Lot: locuri de muncă noapte/oră, recalculări complete/incrementale, controlul idempotenței.
Microbatch: ferestre 1-15 minute pentru tablouri de bord operaționale.
Stream: evenimente prin anvelopă; ferestre (tumbling/glisare/sesiune), semne de apă (date târzii), semantică exact o dată (blocaj + magazin offset).

• "HOP 5m, FEREASTRĂ 1h 'pentru KPI-uri operaționale;
• "TUMBLE 1d' pentru măsurători zilnice;
• SESIUNE 30m' pentru sesiuni.

6) Calitatea și verificabilitatea

Teste de date: schematică, domeniu (intervale), legături referențiale.
Teste de metrică: invarianți (DAU≤MAU), segmente non-goale, așteptări de monotonie (cumulativ).
Reconciliere: între stratul semantic și rapoartele de referință/contabilitate.
Sănătatea datelor: prospețime, completitudine, duplicate, fracție NULL, salturi anormale.
Măsurători în derivă: PSI/KL/JS pe caracteristici cheie, în special pentru măsurători ML.

7) Versioning și migrații

Versiunea de formula este 'METRIC _ NAME _ vN'. Este interzis să modificați „în liniște” definiția fără a schimba versiunea.

• Side-by-side: v1 și v2 sunt numărate în paralel; se efectuează reconcilierea și instruirea utilizatorilor.
• Cut-over: trecerea consumatorilor la v2 în fereastra de încărcare redusă; arhiva v1.
• Recalcularea istoriei: rambursare în funcție de datele istorice; protocol diferență (raport diff).
• Comunicații: changelog, data intrării, cine va fi afectat, instrucțiuni.

8) Modelul de date pentru măsurători

Fapte: cereale (event_id, transaction_id, user_day), timp eveniment, sumă/valori.
Dimensiuni: utilizator, dispozitiv, geografie, canal, produs, calendar; Tipul SCD pentru istoricitate.
Chei: ID-uri surogat, chei de afaceri stabile, tabele de cartografiere.
Anti-duplicate: reguli de identitate (îmbinare utilizator), sesiune „lipire” ferestre.

9) Unități, valute, sezonalitate

Unități/format: unități explicite, rotunjire, scale (jurnal/liniar).
Multicurrency: conversie la cursul de schimb la data tranzacției; stoca atât „prime” și suma normalizată.
Sezonalitate: indici YoY și sezonieri; efecte separate de „vacanță”.

10) Securitate și acces

Row-Level Security (RLS): acces la valori în funcție de țară/marcă/partener.
Securitate la nivel de coloană (CLS) -Masking PII/domenii financiare.
Audit: cine a solicitat metrica, care filtrează, care exportă date.
Diferențierea API: „agregează după rol” vs „încărcări detaliate”.

11) Observabilitate și SLO

Prospețimea SLO: de exemplu, „KPI operațional - lag ≤ 15 min, zilnic - până la ora locală 06:00”.
Disponibilitate SLO: ≥ 99. 9% pentru API/strat semantic.
Alerte: delincventa SLO, salturi metrice, crestere NULL/duplicat, varianta v1 vs v2> X%.
Runbooks: ce trebuie făcut atunci când sunt degradate - pași RCA, rezervă (de exemplu, trecerea la ultima „metrică de instantaneu” valabilă).

12) Experimente și valori

Valori guardrail: latență, reziliență, FPR/FNR pentru scoring.
Definiții uniforme pentru A/B: conversii, retenție, NSM - prin același strat semantic.
Efect minim distinctiv (MDE), analiza puterii: stocați parametrii în cardul metric.
Atribuirea cauzală: politici prin grupurile de ajustare și control.

13) măsurători și consum API

Запросы: 'GET/metrics/{ name}? from = 2025-09-01 & to = 2025-10-01 & dims = country, platform & filters = channel: paid'.
Politici: limite, memorie cache, paginație, „exporturi” idempotente.
Versiuni: 'X-Metric-Version: v2' antet, avertismente de depreciere.

14) Modele și artefacte

Pașaport metric (exemplu)

Cod/Versiune: 'ARPPU _ v3'

Definiție: venitul mediu pe utilizator plătitor pentru perioada

Формула: „suma (revenue_net )/ count_distinct (user_id unde paying_flag=1)”

Granularitate: zi; rollup: săptămână/lună = suma numărătorului/suma numitorului

Surse: 'fact _ payments _ v2', 'dim _ users _ scd'

Unități: moneda „base _ ccy”; conversia la cursul de schimb ca de

Filtre implicite: piețe active, excluderea tranzacțiilor de testare

SLO: prospețime ≤ 1 oră; API ≥ 99 disponibilitate. 9%

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

Proprietari: Monetization Analytics; data revizuirii: 2025-10-01

Check-list metric release

• Definiția și formula convenite, acoperite cu teste
• Obiect semantic creat; descendență documentată
• Backfill și referințe completate
• SLO/alertele sunt configurate; runbook gata
• Drepturile și RLS configurate; PII ascunse
• Versiuni vechi înlocuite în tablouri de bord/experimente
• Changelog/comunicare trimisă

point-in-time SQL pseudo code (exemplu 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) Greșeli frecvente și cum să le evitați

Formula silențioasă editează: întotdeauna prin versiune și changelog.
Măsurători „diferite în fiecare laptop”: Forță pe strat semantic/API.
Zone orare/valute inconsecvente: calendar centralizat și tabel FX.
Contabilitate dublă a utilizatorilor: reguli de rollup și chei unice.
Prospețime opacă: Afișați în mod clar timpul de întârziere/actualizare.
Dependența de un singur inginer: totul este ca un cod, cu o revizuire și un oncall.

Total

Arhitectura metrică este dicționar + strat semantic + calcul robust + guvernare și SLO. Urmând principiile descrise (contracte, teste, versiuni, observabilitate, siguranță), transformați măsurătorile din „dispute de numere” într-un mecanism sustenabil de gestionare a produselor și afacerilor.