მეტრიკის არქიტექტურა

მეტრიკის არქიტექტურა

მეტრიკის არქიტექტურა არის წესების, არტეფაქტებისა და მომსახურების სისტემა, რომელიც უზრუნველყოფს ერთმნიშვნელოვან განმარტებებს, რეპროდუქციულ გაანგარიშებას, გამჭვირვალე წვდომას და ინდიკატორების საიმედო მუშაობას მთელ ორგანიზაციაში. მიზანია, რომ „MAU“, „Retention D30“ ან „ARPPU“ თანაბრად ჩაითვალოს ყველა დაშბორდში, ექსპერიმენტებსა და მოხსენებებში.

1) პრინციპები

1. ჭეშმარიტების ერთი წყარო (Truth Single Source) ფორმულებისა და საცნობარო წიგნებისთვის.
2. სემანტიკის განცალკევება განხორციელებისგან: ბიზნეს განმარტება ცხოვრობს სემანტიკურ ფენაში და არა ყველა SQL/ლეპტოპში.
3. მეტრიკის, სქემების და ფორმულების ვერსიები (v1-v2) კონტროლირებადი ისტორიის მიგრაციით.
4. რეპროდუქცია და ტესტირება: გამოთვლები დეტერმინირებულია, დაფარულია ტესტებით.
5. დაკვირვება: სიახლე, სისრულე, თანმიმდევრულობა და დრიფტი - SLO და ალერტებით.
6. უსაფრთხოება და კონფიდენციალურობა: PII, RLS/CLS შემცირება, აუდიტი.
7. ოპერაცია, როგორც კოდი: განმარტებები, ტრანსფორმაციები, პოლიტიკა - საცავში CI/CD- ით.

2) არქიტექტურის ფენები

წყარო მონაცემები: მოვლენები/გარიგებები, საცნობარო წიგნები, მოდელების ლოგოები/ინფო.
ინტეგრაცია და გაწმენდა: CDC/საგანგებო დატვირთვა, დედაპლატი, დროებითი ზონების გაერთიანება.
მონაცემთა მოდელი (DWH): ვარსკვლავი/ფიფქია, ნელა იცვლება გაზომვები (SCD), სუროგატი გასაღებები.
სემანტიკური მეტრიკის ფენა: ერთიანი განმარტებები, აგრეგაციები, ფილტრები, დროის გრეინი, როლაპის ლოგიკა.
სავარაუდო ფენა: batch/mikrobatch/strim; ფანჯრები, წყლის ეტიკეტები, კლავიშები.
კატალოგი და ლექსიკონი: „მეტრიკის პასპორტი“, ხაზოვანი, მეპატრონეები, უფლებები.
წვდომა და მოხმარება: BI/dashbords, API მეტრიკა, გადმოტვირთვა, ექსპერიმენტები/AB.

3) მონაცემთა კონტრაქტები და მეტრიკა

წყაროს კონტრაქტი (მოვლენები/ცხრილი)

სქემა: ველები, ტიპები, ნულოვანი, პირველადი გასაღები.
SLA: სიახლე (მაგალითად, „10 წუთი ფეხით“), სიხშირე, მაქსიმალური დაკავებული ჩამოსვლა.
ხარისხი: გასაღების უნიკალურობა, დასაშვები მნიშვნელობების დომენები, timezone, imempotenty.
ცვლილებები: სქემის ევოლუციის პოლიტიკა (backward/forward), deprecation გეგმა.

მეტრის კონტრაქტი

სახელი/კოდი: 'RET _ D30 _ v2'

დომეინი/მფლობელი: Product Analytics

განმარტება (ადამიანის ენა)

ფორმულა: SQL/ფსევდოკოდი + შესასვლელი ფანჯრები/სემანტიკური ობიექტები

შეზღუდვა/დროებითი ლოგიკა: დღე/კვირა; წერტილის დროში წესი, timezone

ნაგულისხმები სეგმენტები/ფილტრები

ერთეული და ვალუტა (კურსი/კონვერტაციის თარიღი)

SLO: სიახლე X, სიზუსტე Y, ხელმისაწვდომობა Z

ვერსია/ცვლილების ისტორია/შესვლის თარიღი

Guardrails: დასაშვები დიაპაზონი, ვინსორიზაციის წესები p1/p99

4) მეტრიკის სემანტიკური ფენა

• ელემენტები: გაზომვები (date, country, platform), ფაქტები (events, revenue), მეტრიკა (ARPU, Retention D30), გაანგარიშებული ველები, კალენდარი (მონა/შაბათ, არდადეგები).
• დროის ქცევა: კალენდარული ცხრილი, ლაქები, კოჰორტები, „მოცურების“ ფანჯრები (7/30/90).
• როლაპი და თანმიმდევრულობა: დღეების ჯამი = თვე, ხოლო ორმაგი აღრიცხვის გამორიცხვა (ორმაგი აღრიცხვა).
• Mix-adjustment: ნორმალიზაცია არხების/ქვეყნების მუდმივი მიქსებისთვის გულწრფელი YoY- სთვის.
• მულტივალუტა/ტაიმზონები: ძირითადი ვალუტის მიტანა გარიგების თარიღისთვის; ადგილობრივი და „კანონიკური“ UTC ნაჭრები.

5) გაანგარიშება: ბატჩი, მიკრობატი, ნაკადი

Butch: ღამის/საათების ჯობი, სავსე/არაკრეციული დათვლა, იდემპოტენტურობის კონტროლი.
მიკრობატი: ფანჯრები 1-15 წუთი ოპერატიული დაშბორდებისთვის.
სტრიმი: მოვლენები საბურავის მეშვეობით; ფანჯრები (tumbling/sliding/session), წყლის ეტიკეტები (late data), exactly-once სემანტიკა (გასაღები + offset store).

• 'HOP 5m, WINDO 1h' ოპერატიული KPI- სთვის;
• 'TUMBLE 1d' დღის მეტრიკებისთვის;
• 'SESSION 30 მ' სესიებისთვის.

6) ხარისხი და შემოწმება

მონაცემთა ტესტები: სქემატური, აფეთქების ღუმელი (დიაპაზონი), რეფერენდუმი.
მეტრიკის ტესტები: ინვარიანტები (DAU - MAU), არაკონტროლირებადი სეგმენტები, ერთფეროვნების მოლოდინები (კუმულატორები).
Creconciliation: სემანტიკურ ფენას და რეფერენდუმის ანგარიშებს/ბუღალტრულ აღრიცხვას შორის.
Data Health: სიახლე, კომპლექტი, დუბლიკატები, NULL წილი, არანორმალური რბოლა.
დრიფტის მეტრიკა: PSI/KL/JS საკვანძო ფინიკებზე, განსაკუთრებით ML მეტრიკისთვის.

7) ვერსიები და მიგრაცია

ფორმულის ვერსია: 'METRIC _ NAME _ vN'. აკრძალულია განმარტების „ჩუმად“ შეცვლა ვერსიის შეცვლის გარეშე.

• Side-by-side: v1 და v2 პარალელურად განიხილება; ტარდება მომხმარებლის შემოწმება და ტრენინგი.
• Cut-over: მომხმარებელთა შეცვლა v2 დაბალი დატვირთვის ფანჯარაში; არქივი v1.
• ისტორიის დათვლა: backfill ისტორიული მონაცემების მიხედვით; განსხვავების პროტოკოლი (დიფტის ანგარიში).
• კომუნიკაციები: changelog, შესვლის თარიღი, რომელზეც გავლენას მოახდენს ინსტრუქციები.

8) მეტრიკის მონაცემთა მოდელი

ფაქტები: მარცვლეული (event _ id, transaction _ id, user _ day), მოვლენის დრო, თანხა/მნიშვნელობა.
გაზომვები: მომხმარებელი, მოწყობილობა, გეოგრაფია, არხი, პროდუქტი, კალენდარი; SCD ტიპი ისტორიულობისთვის.
გასაღებები: სუროგატი ID, სტაბილური ბიზნეს გასაღებები, შესაბამისობის ცხრილი.
ანტი დუბლი: თვითმყოფადობის წესები, სესიების „წებოვანი“ ფანჯრები.

9) ერთეულები, ვალუტები, სეზონურობა

ერთეულები/ფორმატი: მკაფიო გაზომვის ერთეულები, დამრგვალება, მასშტაბები (ლოგინი/ხაზოვანი).
მულტივალუტა: კურსის კონვერტაცია ოპერაციის თარიღამდე; შეინახეთ როგორც „ნედლი“, ასევე ნორმალიზებული თანხა.
სეზონური: YoY და სეზონური ინდექსები; ინდივიდუალური „სადღესასწაულო“ ეფექტები.

10) უსაფრთხოება და წვდომა

Row-Level Security (RLS): მეტრიკებზე წვდომა ქვეყნის/ბრენდის/პარტნიორის კონტექსტში.
Column-Level Security (CLS): PII/ფინანსური ველების შენიღბვა.
აუდიტი: ვინ მოითხოვა მეტრი, რა ფილტრები, რომელი მონაცემების ექსპორტი.
API დიფერენციაცია: „დანაყოფები როლებზე“ vs „დეტალური გადმოტვირთვის შესახებ“.

11) დაკვირვება და SLO

SLO სიახლე: მაგალითად, „ოპერატიული KPI - ლაგი 15 წუთი, ყოველდღიური - ადგილობრივი დროის 06:00 საათამდე“.
SLO ხელმისაწვდომი: 99 ევრო. 9% API/სემანტიკური ფენისთვის.
ალერტები: შეფერხება SLO, მეტრული ნახტომი, NULL/დუბლიკატების ზრდა, შეუსაბამობა v1 vs v2> X%.
Runbooks: რა უნდა გააკეთოს დეგრადაციის დროს - ნაბიჯები RCA, fallback (მაგალითად, გადასვლა ბოლო მოქმედი „თოვლის მეტრიკზე“).

12) ექსპერიმენტები და მეტრიკა

Guardrail მეტრიკა: ლატენტობა, წინააღმდეგობა, FPR/FNR მორიელებისთვის.
A/B- სთვის ერთიანი განმარტებები: კონვერტაცია, შენარჩუნება, NSM - იგივე სემანტიკური ფენის მეშვეობით.
მინიმალური გამორჩეული ეფექტი (MDE), ძალაუფლების ანალიზი: პარამეტრების შენახვა მეტრიკის ბარათში.
კაუზალური ატრიბუტი: პოლიტიკოსები mix-adjustment და საკონტროლო ჯგუფებში.

13) API მეტრიკა და მოხმარება

Запросы: `GET /metrics/{name}?from=2025-09-01&to=2025-10-01&dims=country,platform&filters=channel:paid`.
პოლიტიკოსები: ლიმიტები, ქეში, პაგინაცია, იდემპოტენტური „ექსპორტები“.
ვერსიები: სათაური 'X-Metric-Version: v2', დეპრესიის გაფრთხილებები.

14) შაბლონები და ნიმუშები

მეტრიკის პასპორტი (მაგალითი)

კოდი/ვერსია: 'ARPPU _ v3'

განმარტება: გადახდილი მომხმარებლის საშუალო შემოსავალი პერიოდისთვის

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

მარცვალი: დღე; rollup: კვირა/თვე = მრიცხველის ჯამი/მნიშვნელის ჯამი

წყაროები: 'fact _ payments _ v2', 'dim _ users _ scd'

ერთეულები: ვალუტა 'base _ ccy'; კონვერტაცია გაცვლითი კურსის თარიღზე

ნაგულისხმევი ფილტრები: აქტიური ბაზრები, გამორიცხეთ ტესტის გარიგებები

SLO: სიახლე 1 საათი; API ხელმისაწვდომობა 99. 9%

Guardrails: ARPPU ∈ [0; 10 000]; ვინსორიზაცია p1/p99

მფლობელები: Monetization Analytics; აუდიტის თარიღი: 2025-10-01

მეტრის გამეორების სია

• განმარტება და ფორმულა შეთანხმებულია, დაფარულია ტესტებით

შეიქმნა სემანტიკური ობიექტი; დოკუმენტაცია

• Backfill და რეფერენდუმის შერიგება დასრულდა
• SLO/alertes მორგებული; runbook მზად არის
• უფლებები და RLS მორგებულია; PII იმალება
• ძველი ვერსიები შეიცვალა დაშბორდებში/ექსპერიმენტებში
• Changelog/კომუნიკაცია იგზავნება

SQL ფსევდო კოდი წერტილში (მაგალითი 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) ხშირი შეცდომები და როგორ მოვერიდოთ მათ

ფორმულების მშვიდი რედაქტირება: ყოველთვის ვერსიისა და ჩანგელოგის საშუალებით.
მეტრიკა „თითოეულ ლეპტოპში განსხვავებულად“: აიძულეთ სემანტიკური ფენა/API.
არაკოორდინირებული დროზონები/ვალუტები: ცენტრალიზებული კალენდარი და FX ცხრილი.
მომხმარებელთა ორმაგი ჩანაწერი: როლაპის წესები და უნიკალური გასაღებები.
გაუმჭვირვალე სიახლე: აშკარად აჩვენეთ lag/განახლების დრო.
დამოკიდებულება ერთ ინჟინერზე: ყველაფერი კოდის მსგავსია, შურისძიებით და ონკოლით.

შედეგი

მეტრიკის არქიტექტურა არის ლექსიკონი + სემანტიკური ფენა + საიმედო გაანგარიშება + ჰოვერნანსი და SLO. აღწერილი პრინციპების გათვალისწინებით (კონტრაქტები, ტესტები, ვერსიები, დაკვირვება, უსაფრთხოება), თქვენ მეტრიკებს „ციფრების დავებიდან“ გადააქცევთ პროდუქტისა და ბიზნესის მართვის სტაბილურ მექანიზმად.