Architettura delle metriche

Architettura delle metriche

L'architettura delle metriche è un sistema di regole, manufatti e servizi che garantiscono una definizione univoca, un calcolo riproduttivo, un accesso trasparente e un funzionamento affidabile degli indicatori in tutta l'organizzazione. L'obiettivo è che MAU, Retention D30 o ARPU siano considerati uguali in tutti i dashboard, esperimenti e rapporti.

1) Principi

1. Un'unica fonte di verità (Single Source of Truth) per formule e riferimenti.
2. Separazione semantica dall'implementazione: la definizione aziendale vive in un livello semantico e non in ogni notebook SQL.
3. Versioning di metriche, diagrammi e formule (v1→v2) con una storia guidata dalla migrazione.
4. Riproduzione e testabilità: calcoli determinati, coperti da test.
5. Osservabilità: freschezza, completezza, consistenza e deriva, con SLO e alert.
6. Sicurezza e privacy: riduzione del PI, RLS/CLS, controllo.
7. L'operazione come codice: definizioni, trasformazioni, criteri - in un repository con CI/CD.

2) Livelli di architettura

I dati di origine sono eventi/transazioni, guide, fogli di modelli/infra.
Integrazione e pulizia: CDC/caricamento incrementale, deadup, unificazione delle zone temporali.
Modello dati (DWH) - Stella/fiocco di neve, dimensioni lente (SCD), chiavi surrogate.
Livelli semantici di metriche: definizioni, aggregazioni, filtri, time grain, roll-logic.
Livello di calcolo: batch/microbatch/strame; finestre, etichette d'acqua, impronte di chiavi.
Catalogo e dizionario: «passaporto metrico», lineage, proprietari, diritti.
Accesso e consumo: BI/dashboard, API metriche, scarichi, esperimenti/AV.

3) Contratti di dati e metriche

Contratto sorgente (eventi/tabelle)

Schema: campi, tipi, nullità, chiave primaria.
SLA: freschezza (ad esempio, «≤10 minuti»), frequenza, massimo ritardo della parrocchia.
Qualità: unicità della chiave, domini di valori validi, timezone, idempotenza.
Modifiche: strategia di evoluzione dello schema (backward/forward), piano di deprecazione.

Contratto metrico

Nome/codice: 'RET _ D30 _ v2'

Domain/proprietario: Product Analytics

Definizione (in linguaggio umano)

Formula: SQL/pseudocode + vetrine di ingresso/oggetti semantici

Granularità/logica temporale: day/week; point-in-time regole, timezone

Segmenti/filtri predefiniti

Unità e valute (tasso/data di conversione)

SLO: freschezza ≤ X, precisione ≥ Y, disponibilità ≥ Z

Versione/cronologia delle modifiche/data di accesso

Garrails: intervalli validi, regole di Vinzorizzazione p1/p99

4) Livello semantico delle metriche

• Elementi: misure (date, country, platform), fatti (events, revenue), metriche (ARPU, Retention D30), campi calcolabili, calendario (schiavo/weekend, festività).
• Comportamento del tempo: tabelle di calendario, lame, coorti, finestre «scorrevole» (7/30/90).
• Rollap e consistenza: importo giornaliero = mese, escludendo la doppia contabilità (distinct users).
• Mix-adjustment - Normalizzazione con un mix costante di canali/paesi per un corretto YoY.
• Multivaluta/timsone: indicazione della valuta di base alla data di transazione; Taglio UTC locale e canonico.

5) Calcolo: batch, microbatch, bucato

Batch: giubbotti notturni/orari, conteggi completi/incrementali, controllo idampotenza.
Microbatch: finestre da 1 a 15 minuti per i dashboard operativi.
Gli eventi attraverso il pneumatico; finestre (tumbling/sliding/sessions), etichette ad acqua (late data), exactly-once semantica (deadup chiave + offset store).

• "HOP 5m, WINDOW 1h'per i KPI operativi;
• «TUMBLE 1d» per le metriche diurne;
• SESSIONE 30m per le sessioni.

6) Qualità e validità

I test dei dati sono schematici, di dominio (intervalli), di correlazione referenziale.
Test metrici: invarianti (DAU≤MAU), segmenti non vuoti, in attesa di monotonia (cumulativi).
Incrociature - Tra il livello semantico e i report di riferimento/contabilità.
Data health: freschezza, completeness, duplicati, quota NULL, corse anomale.
Metriche della deriva: PSI/KL/JS su fiocchi chiave, soprattutto per le metriche ML.

7) Versioning e migrazione

Versione della formula «METRIC_NAME_vN». Non è consentito modificare silenziosamente la definizione senza cambiare versione.

• Side-by-side: v1 e v2 sono considerati paralleli; Verifica e formazione degli utenti.
• Cut-over: passaggio dei consumatori a v2 in una finestra a basso carico archivio v1.
• Riconteggio della storia: backfill in base ai dati storici; protocollo di differenza (report differente).
• Comunicazioni: changelog, data di ingresso, chi viene colpito, istruzioni.

8) Modello di dati per metriche

Fatti: grano (event _ id, communication _ id, user _ day), ora dell'evento, somma/quantità.
Misurazioni: utente, dispositivo, geografia, canale, prodotto, calendario; Tipo SCD per la storicità.
Chiavi: ID surrogato, chiavi aziendali stabili, tabelle di corrispondenza (mapping).
Anti-ripresa: regole di identità (user merge), finestre di pendenza delle sessioni.

9) Unità, valute, stagionalità

Unità/formato: unità nitide, arrotondamenti, scala (loga/lineare).
Multivaluta: conversione di rotta alla data dell'operazione; conservare sia la somma cruda che la somma normalizzata.
Stagionalità: indici YoY e stagionali; singoli effetti «natalizi».

10) Sicurezza e accesso

Row-Level Security (RLS) - Accesso alle metriche nel taglio paese/marchio/partner.
Column-Level Security (CLS) - Maschera i campi finanziari.
Controllo: chi ha richiesto la metrica, quali filtri, quali dati ha esportato.
Differenziazione API: «aggregazioni per ruolo» vs «caricamento dettagliato».

11) Osservabilità e SLO

La SLO di freschezza, per esempio, «KPI ≤ 15 minuti, ogni giorno fino alle 6:00 locali».
SLO disponibilità: ≥ 99. 9% per il livello API/semantico.
Alert: ritardo SLO, picchi di metriche, crescita NULL/duplicati, variazione v1 vs v2> X%.
Runbooks: cosa fare in caso di degrado - passi RCA, fallback (ad esempio, passare all'ultima valida «snepshot metrica»).

12) Esperimenti e metriche

Garrail metriche: latitanza, tolleranza, FPR/FNR per gli schemi.
Definizioni comuni per A/B: conversione, ritenzione, NSM - attraverso lo stesso livello semantico.
Effetto minimo differente (MDE), analisi power - Memorizza i parametri nella scheda metrica.
Assegnazione casuale: criteri mix-adjustment e gruppi di controllo.

13) API metriche e consumo

Запросы: `GET /metrics/{name}?from=2025-09-01&to=2025-10-01&dims=country,platform&filters=channel:paid`.
Criteri: limiti, cache, paginazione, esporti idipotenti.
Versione: titolo «X-Metric-Variante: v2», avvisi di deprecazione.

14) Modelli e manufatti

Passaporto metrico (esempio)

Codice/versione: 'ARPPU _ v3'

Definizione: ricavi medi per utente pagante per periodo

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

Granularità: giorno; rollup: settimana/mese = somma numeratore/somma denominatore

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

Unità: valuta base _ ccy; conversione di rotta a data

Filtri predefiniti: mercati attivi, escludere transazioni di prova

SLO: freschezza di 1 ora; disponibilità API 99. 9%

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

Proprietari: Monetization Analytics; data di revisione 2025-10-01

Check-list release metriche

• Definizione e formula sono coerenti, coperti da test
• Oggetto semantico creato. lineage documentato
• Backfill e incroci con l'arbitro completati
• SLO/alert configurati; runbook pronto
• Diritti e RLS configurati; PII nascosto
• Le vecchie versioni sono state sostituite in dashboard/esperimenti
• Changelog/comunicazione inviati

pseudo-codice SQL point-in-time (esempio 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) Errori frequenti e come evitarli

Modifiche silenziose alle formule: sempre attraverso la versione e changelog.
Le metriche «diverse in ogni notebook» sono obbligate a un livello/API semantico.
Timsons/valute incoerenti: calendario centralizzato e tabella FX.
Doppia contabilità utente: regole di rollup e chiavi univoche.
Freschezza opaca: mostra chiaramente la lega/ora di aggiornamento.
Dipendenza da un solo ingegnere, tutto come un codice, con la gelosia e la oncola.

Totale

L'architettura delle metriche è un dizionario + livello semantico + calcolo affidabile + revernance e SLO. Seguendo i principi descritti (contratti, test, versioni, osservabilità, sicurezza), si trasformano le metriche da «discussioni sui numeri» in un meccanismo sostenibile di gestione del prodotto e del business.