Architektura metryczna

Architektura metryczna

Architektura metryki jest systemem zasad, artefaktów i usług, które zapewniają jednoznaczne definicje, powtarzalne obliczenia, przejrzysty dostęp i niezawodne działanie wskaźników w całej organizacji. Celem jest uznanie „MAU”, „Retention D30” lub „ARPPU” za takie same we wszystkich deskach rozdzielczych, eksperymentach i raportach.

1) Zasady

1. Pojedyncze Źródło Prawdy dla formuł i ksiąg referencyjnych.
2. Oddzielenie semantyki od implementacji: definicja biznesu żyje w warstwie semantycznej, a nie w każdym SQL/laptopie.
3. Mierniki wersji, schematy i formuły (v1 → v2) z zarządzaną migracją historii.
4. Odtwarzalność i testowalność: obliczenia są deterministyczne, objęte badaniami.
5. Obserwowalność: świeżość, pełnia, konsystencja i dryf - z SLO i wpisy.
6. Bezpieczeństwo i prywatność: minimalizacja PII, RLS/CLS, audyt.
7. System operacyjny jako kod: definicje, przekształcenia, zasady - w repozytorium z CI/CD.

2) Warstwy architektury

Dane źródłowe: wydarzenia/transakcje, księgi referencyjne, dzienniki modeli/infra.
Integracja i czyszczenie: CDC/przyrostowe obciążenie, odpływ, ujednolicenie stref czasowych.
Model danych (DWH): gwiazda/płatek śniegu, powoli zmieniające się pomiary (SCD), klucze zastępcze.
Warstwa semantyczna metryk: jednolite definicje, agregacje, filtry, ziarno czasu, logika rollup.
Warstwa projektowa: partia/mikrobatch/strumień; okna, znaki wodne, klucze.
Katalog i słownik: „metryki paszportowe”, rodowód, właściciele, prawa.
Dostęp i zużycie: BI/deski rozdzielcze, mierniki API, przesyłki, eksperymenty/AB.

3) Umowy dotyczące danych i metryk

Umowa źródłowa (wydarzenia/tabele)

Schemat: pola, typy, nieważność, klucz podstawowy.
SLA: świeżość (na przykład „≤ 10 minut opóźnienia”), częstotliwość, maksymalny opóźniony przylot.
Jakość: wyjątkowość klucza, prawidłowe domeny wartości, timezon, idempotencja.
Zmiany: polityka ewolucji systemu (do tyłu/do przodu), plan odchylenia.

Umowa metryczna

Nazwa/identyfikator: 'RET _ D30 _ v2'

Domaine/właściciel: Analityka produktów

Definicja (w języku ludzkim)

Formuła: SQL/pseudokoda + sklepy wejściowe/obiekty semantyczne

Ziarnistość/logika czasowa: dzień/tydzień; zasady punktualne, timezon

Domyślne segmenty/filtry

Jednostki i waluty (kurs wymiany/data)

SLO: świeżość ≤ X, dokładność ≥ Y, dostępność ≥ Z

Wersja/Historia zmian/Data wejścia w życie

Poręcze: ważne zakresy, zasady Winzorization p1/p99

4) Warstwa semantyczna mierników

• Elementy: wymiary (data, kraj, platforma), fakty (wydarzenia, dochody), mierniki (ARPU, Retention D30), pola obliczeniowe, kalendarz (praca/weekend, wakacje).
• Zachowanie czasu: tabele kalendarza, opóźnienia, kohorty, okna „przesuwne” (7/30/90).
• Rollup i konsystencja: ilość według dnia = miesiąc, z wyłączeniem podwójnego liczenia (odrębni użytkownicy).
• Mix-adjustment: normalizacja do stałej mieszanki kanałów/krajów dla uczciwego YoY.
• Wielokrotność/strefy czasowe: dostosowane do waluty bazowej w dniu transakcji; plastry lokalne i „kanoniczne” UTC.

5) Obliczanie: partia, mikrobatch, strumień

Partia: praca nocna/godzinna, ponowne obliczenia pełne/przyrostowe, kontrola idempotencji.
Mikrobatch: okna 1-15 minut dla desek rozdzielczych.
Strumień: wydarzenia przez oponę; okna (tumbling/sliding/session), znaki wody (późne dane), dokładnie raz semantyka (impas + sklep offsetowy).

• „HOP 5m, WINDOW 1h” dla KPI operacyjnych;
• "BUMBLE 1d' dla dziennych mierników;
• SESJA 30m' dla sesji.

6) Jakość i weryfikowalność

Testy danych: schemat, domena (zakresy), odnośniki.
Badania mierników: niezmienne (DAU ≤ MAU), segmenty niepuste, oczekiwania dotyczące monotonii (skumulowane).
Uzgodnienie: między warstwą semantyczną a sprawozdaniami referencyjnymi/rachunkowością.
Zdrowie danych: świeżość, kompletność, duplikaty, frakcja NULL, nieprawidłowe skoki.
Metryki dryfujące: PSI/KL/JS na kluczowych cechach, szczególnie dla mierników ML.

7) Weryfikacja i migracja

Wersja formuły jest 'METRIC _ NAME _ vN'. Zabrania się „cichej” zmiany definicji bez zmiany wersji.

• Side-by-side: v1 i v2 są liczone równolegle; przeprowadza się uzgadnianie i szkolenie użytkowników.
• Cut-over: przełączanie konsumentów na v2 w oknie niskiego obciążenia; archiwum v1.
• Ponowne obliczenie historii: zasypka według danych historycznych; protokół różnicy (raport różnicowy).
• Komunikacja: changelog, data wejścia, kto będzie miał wpływ, instrukcje.

8) Model danych dla mierników

Fakty: zboże (event_id, transaction_id, user_day), czas zdarzenia, suma/wartości.
Wymiary: użytkownik, urządzenie, geografia, kanał, produkt, kalendarz; Typ SCD dla historyczności.
Klucze: zastępcze identyfikatory, stabilne klucze biznesowe, tabele mapowania.
Anty-duplikaty: reguły tożsamości (połączenie użytkownika), okna „klejenia” sesji.

9) Jednostki, waluty, sezonowość

Jednostki/format: jednostki jednoznaczne, zaokrąglanie, wagi (dziennik/liniowy).
Wielokrotność: konwersja według kursu wymiany w dniu transakcji; przechowywać zarówno „surową”, jak i znormalizowaną ilość.
Sezonowość: indeksy YoY i sezonowe; oddzielne efekty „wakacji”.

10) Bezpieczeństwo i dostęp

Row-Level Security (RLS): dostęp do mierników według kraju/marki/partnera.
Bezpieczeństwo na poziomie kolumn (CLS) -Masking PII/pola finansowe.
Audyt: kto poprosił o metrykę, która filtruje, która eksportowała dane.
Różnicowanie API: „agregaty według roli” vs „szczegółowe przesłania”.

11) Obserwowalność i SLO

Świeżość SLO: na przykład „operacyjny KPI - lag ≤ 15 min, dziennie - do godziny 06:00 czasu lokalnego”.
Dostępność SLO: ≥ 99. 9% dla warstwy API/semantycznej.
Wpisy: Przestępczość SLO, skoki metryczne, wzrost NULL/duplikat, wariancja v1 vs v2> X%.
Runbooks: co robić po zdegradowaniu - kroki RCA, fallback (na przykład przejście na ostatni ważny „migawkowy metric”).

12) Eksperymenty i metryki

Mierniki bariery: opóźnienie, odporność, FPR/FNR do punktacji.
Jednolite definicje A/B: konwersje, retencja, NSM - przez tę samą warstwę semantyczną.
Minimalny odróżnialny efekt (MDE), analiza mocy: parametry przechowywania w karcie metrycznej.
Przypisanie przyczynowe: zasady według grup mix-adjustment i kontroli.

13) Wskaźniki API i konsumpcja

Маброса: 'GET/metrics/{ name}? od = 2025-09-01 & to = 2025-10-01 & dims = kraj, platforma i filtry = kanał: płatny'.
Polityka: limity, pamięć podręczna, paginacja, idempotent „eksport”.
Wersje: nagłówek 'X-Metric-Version: v2', ostrzeżenia deprecacji.

14) Wzory i artefakty

Paszport metryczny (przykład)

Kod/Wersja: „ARPPU _ v3”

Definicja: średni dochód na płatnego użytkownika za dany okres

Моркула: „suma (revenue_net )/ count_distinct (user_id, gdzie paying_flag=1)”

Ziarnistość: dzień; rollup: tydzień/miesiąc = suma licznika/mianownika

Źródła: 'fact _ payments _ v2', 'dim _ users _ scd'

Jednostki: waluta „base _ ccy”; przeliczenie według kursu wymiany na

Filtry domyślne: aktywne rynki, wykluczyć transakcje testowe

SLO: świeżość ≤ 1 godzina; API ≥ 99 dostępność. 9%

Szyny ochronne: ARPPU ≤ [0; 10 000]; winzoryzacja p1/p99

Właściciele: Monetization Analytics; data rewizji: 2025-10-01

Lista kontrolna wydania metrycznego

• Uzgodniona definicja i formuła, objęte badaniami
• Stworzony obiekt semantyczny; rodowód udokumentowany
• Uzupełnione zasypki i referencje
• SLO/alerty są skonfigurowane; runbook gotowy
• Prawa i RLS skonfigurowane; PII ukryte
• Stare wersje zastąpione deskami rozdzielczymi/eksperymentami
• Changelog/komunikat wysłany

Kod pseudo SQL w czasie (przykład D30 retencji)

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) Częste błędy i jak ich uniknąć

Cicha formuła edytuje: zawsze poprzez wersję i changelog.
„Różne w każdym laptopie” metryki: Siła na warstwie semantycznej/API.
Niespójne strefy czasowe/waluty: scentralizowany kalendarz i tabela FX.
Podwójna księgowość użytkownika: zasady rollup i unikalne klucze.
Nieprzezroczysta świeżość: Wyraźnie pokazać czas opóźnienia/aktualizacji.
Zależność od jednego inżyniera: wszystko jest jak kod, z recenzją i oncall.

Razem

Architektura metryki jest słownikiem + warstwa semantyczna + solidne obliczenia + zarządzanie i SLO. Stosując się do opisanych zasad (kontrakty, testy, wersje, obserwowalność, bezpieczeństwo), zmieniasz wskaźniki z „sporów liczbowych” w zrównoważony mechanizm zarządzania produktem i biznesem.