Architecture métrique

Architecture métrique

L'architecture des métriques est un système de règles, d'artefacts et de services qui fournissent des définitions claires, un calcul reproductible, un accès transparent et une exploitation fiable des indicateurs dans toute l'organisation. L'objectif est que « MAU », « Retraite D30 » ou « ARPPU » soient considérés comme identiques dans tous les dashboards, expériences et rapports.

1) Principes

1. Source unique de vérité (Single Source of Truth) pour les formules et les manuels.
2. Séparer la sémantique de la mise en œuvre : la définition d'entreprise vit dans la couche sémantique, pas dans chaque SQL/ordinateur portable.
3. Versioner des métriques, des schémas et des formules (v1→v2) avec une migration d'historique contrôlée.
4. Reproductibilité et testabilité : les calculs sont déterministes, couverts de tests.
5. Observabilité : fraîcheur, plénitude, consistance et dérive - avec SLO et alerts.
6. Sécurité et vie privée : minimisation des IPI, RLS/CLS, audit.
7. L'opération en tant que code : définitions, transformations, politiques - dans le référentiel avec CI/CD.

2) Couches d'architecture

Source : événements/transactions, annuaires, logs de modèle/infra.
Intégration et nettoyage : CDC/chargement incrémental, déduplication, unification des zones temporelles.
Modèle de données (DWH) : étoile/flocon de neige, mesures à variation lente (SCD), clés de substitution.
Couche sémantique de métriques : définitions uniques, agrégations, filtres, grain de temps, logique rollap.
Couche de calcul : batch/microbatch/stream ; fenêtres, marques d'eau, dedup par clés.
Catalogue et dictionnaire : « passeport métrique », lineage, propriétaires, droits.
Accès et consommation : BI/dashboards, métriques API, décharges, expériences/AV.

3) Contrats de données et métriques

Contrat source (événements/tableaux)

Schéma : champs, types, nullité, clé primaire.
SLA : fraîcheur (par exemple « ≤10 minutes de larme »), fréquence, paroisse maximale retardée.
Qualité : unicité de la clé, domaines valides, timezone, idempotence.
Changements : politique d'évolution du schéma (backward/forward), deprecation-plan.

Contrat métrique

Nom/code : 'RET _ D30 _ v2'

Domaine/propriétaire : Product Analytics

Définition (en langage humain)

Formule : SQL/pseudo-code + vitrines d'entrée/objets sémantiques

Granularité/logique temporelle : jour/semaine ; les règles du point-in-time, timezone

Segments/filtres par défaut

Unités et devises (taux/date de conversion)

SLO : fraîcheur ≤ X, précision ≥ Y, disponibilité ≥ Z

Version/historique des modifications/date d'entrée

Guardrails : fourchettes admissibles, règles de vinzorisation p1/p99

4) La couche sémantique des métriques

• Éléments : mesures (date, pays, plateforme), faits (événements, revenu), métriques (ARPU, retraite D30), champs calculés, calendrier (esclave/week-end, vacances).
• Comportement temporel : tables de calendrier, langes, cohortes, fenêtres « glissantes » (7/30/90).
• Rollap et consistance : somme par jour = mois, tout en excluant la double comptabilité (distinct users).
• Mix-adjustment : normalisation sous un mélange constant de canaux/pays pour un YoY honnête.
• Multivalut/Timzones : amène à la monnaie de base à la date de la transaction ; les tranches UTC locales et « canoniques ».

5) Calcul : batch, microbatch, stream

Batch : jobs nocturnes/horaires, recalculations complètes/incrémentielles, contrôle de l'idempotence.
Microbatch : fenêtres de 1 à 15 minutes pour les dashboards opérationnels.
Stream : événements à travers le pneu ; fenêtres (tumbling/sliding/session), marques d'eau (late data), sémantique exactly-once (dedup par clé + offset store).

• 'HOP 5m, WINDOW 1h 'pour les KPI opérationnels ;
• « TUMBLE 1d » pour les métriques diurnes ;
• « SESSION 30m » pour les sessions.

6) Qualité et vérifiabilité

Tests de données : schématiques, domaines (gammes), liens de référence.
Tests métriques : invariants (DAU≤MAU), segments non vides, attentes de monotonie (cumulatifs).
Rapprochements (reconciliation) : entre la couche sémantique et les rapports de référence/comptabilité.
Data health : fraîcheur, completeness, doublons, part NULL, sauts anormaux.
Mesures de dérive : PSI/KL/JS sur les fiches clés, en particulier pour les mesures ML.

7) Versioning et migration

Version de la formule : 'METRIC _ NAME _ vN'. Il est interdit de changer la définition sans changer de version.

• Side-by-side : v1 et v2 sont comptés en parallèle ; le rapprochement et la formation des utilisateurs sont effectués.
• Cut-over : Commuter les consommateurs en v2 dans la fenêtre de faible charge ; archives v1.
• Recalculer l'histoire : backfill à partir de données historiques ; le procès-verbal de la différence (diff-report).
• Communications : changelog, date d'entrée, personne touchée, instructions.

8) Modèle de données pour les métriques

Faits : grain (event_id, transaction_id, user_day), heure de l'événement, somme/quantité.
Mesures : utilisateur, appareil, géographie, canal, produit, calendrier ; Type SCD pour l'historicité.
Clés : ID de substitution, clés d'affaires stables, tables de correspondance (mapping).
Anti-doublage : règles d'identité (merge user), fenêtres « scintillantes » des sessions.

9) Unités, devises, saisonnalité

Unités/format : unités explicites, arrondis, échelles (log/linéaire).
Multivalut : conversion au taux de change à la date de l'opération ; conserver à la fois le montant « brut » et le montant normalisé.
Saisonnalité : YoY et indices saisonniers ; des effets « festifs » distincts.

10) Sécurité et accès

Row-Level Security (RLS) : accès aux métriques en coupe pays/marque/partenaire.
Column-Level Security (CLS) : masquage des champs PII/Finances.
Audit : qui a demandé la métrique, quels filtres, quelles données ont été exportées.
Différenciation API : « agrégats par rôle » vs « déchargement détaillé ».

11) Observabilité et SLO

SLO de fraîcheur : par exemple, « KPI opérationnel - lag ≤ 15 min, quotidien - jusqu'à 06h00 heure locale ».
Disponibilité SLO : ≥ 99. 9 % pour l'API/couche sémantique.
Alerts : retard de SLO, sauts de métriques, croissance NULL/duplicata, divergence v1 vs v2> X %.
Runbooks : que faire en cas de dégradation - étapes RCA, fallback (par exemple, passer à la dernière « métrique de snepshot »).

12) Expériences et métriques

Métriques de garde : latence, tolérance aux pannes, FPR/FNR pour les scores.
Définitions uniques pour A/B : conversions, rétention, NSM - à travers la même couche sémantique.
Effet minimalement distingué (MDE), power-analyse : stockez les paramètres dans la carte métrique.
Attribution causale : politiques par mix-adjustment et groupes de contrôle.

13) API métriques et consommation

Запросы: `GET /metrics/{name}?from=2025-09-01&to=2025-10-01&dims=country,platform&filters=channel:paid`.
Politiques : limites, cache, pagination, idempotent « exportations ».
Versions : titre « X-Metric-Version : v2 », avertissements de déprécation.

14) Modèles et artefacts

Passeport métrique (exemple)

Code/version : 'ARPPU _ v3'

Définition : Chiffre d'affaires moyen par utilisateur payant pour la période

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

Granularité : jour ; rollup : semaine/mois = somme numérateur/somme dénominateur

Sources : 'fact _ payments _ v2', 'bou _ users _ scd'

Unités : devise 'base _ ccy' ; conversion au taux de change à la date

Filtres par défaut : marchés actifs, exclure les transactions de test

SLO : fraîcheur ≤ 1 h ; Disponibilité de l'API ≥ 99. 9%

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

Propriétaires : Monetization Analytics ; date de révision : 2025-10-01

Check-list de la version métrique

• La définition et la formule sont harmonisées, couvertes de tests
• Objet sémantique créé ; lineage documenté
• Backfill et les rapprochements avec le référent sont terminés
• SLO/alerties personnalisés ; runbook est prêt
• Droits et RLS configurés ; PII caché
• Les anciennes versions ont été remplacées dans les dashboards/expériences
• Changelog/communication envoyé

Pseudo-code SQL point-in-time (exemple Retentation 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) Erreurs fréquentes et comment les éviter

Modifications silencieuses des formules : toujours à travers la version et changelog.
Métriques « dans chaque ordinateur portable différemment » : forcer à la couche sémantique/API.
Temps/devises incohérents : calendrier centralisé et table FX.
Double comptabilisation des utilisateurs : règles rollap et clés uniques.
Fraîcheur opaque : montrez clairement le temps de rafraîchissement.
Dépendance à un seul ingénieur : tout est comme un code, avec de la rhubarbe et de l'oncole.

Résultat

L'architecture métrique est un dictionnaire + couche sémantique + calcul fiable + howernance et SLO. En suivant les principes décrits (contrats, tests, versions, observabilité, sécurité), vous transformez les métriques de la « controverse numérique » en un mécanisme durable de gestion des produits et des entreprises.