API მეტრული ოპერაციები

1) დანიშნულება და პასუხისმგებლობის სფერო

• თანმიმდევრული SLI/SLO (ლოგინი, ანაბარი, განაკვეთი, დასკვნა);
• KRI (ადრეული რისკის ინდიკატორები: PSP/KYC/რიგები/რეპლიკაცია);
• ბიზნეს მეტრიკა (GEO/PSP/ბანკებისთვის ავტორიზაციების წარმატება, წარმატებული განაკვეთების წილი, ძირითადი ბილიკების ხანგრძლივობის p95/p99);
• უსაფრთხო, იაფი და პროგნოზირებადი კითხვა დაშბორდების, ალერტინგის, სტატუსის გვერდების, ანგარიშგების შესახებ.

2) არქიტექტურული პრინციპები

Read-heavy, write-few: API მხოლოდ კითხულობს აგრეგაციებს TSDB/ქეში.
SLO-first: პასუხები პროგნოზირებულია დროულად; შეცდომები და დეგრადაცია - გამჭვირვალე სიგნალი.
Cost: downsampling, კვოტები, კანარის ფიჩები SDK- ში.
Privacy-by-design: არა PII მეტამონაცემებში/ეტიკეტებში; ნიშნები, გეო-კარიბჭე, SoD.
Multi-tenant: იზოლაცია ბრენდის/რეგიონის/გარემოს მიხედვით.

3) მონაცემთა მოდელი (ზედაპირული)

სერია metric = 'metric _ id' + 'labels {' + 'timestamp' + 'value' (+ სურვილისამებრ 'exemplar {trace _ id =...').

3. 1 კატეგორია

SLI/SLO: `auth_success_rate`, `bet_settle_p99_ms`, `withdraw_tat_p95_ms`, `api_5xx_rate`.
KRI: `queue_consumer_lag`, `db_replication_lag`, `psp_soft_decline_rate`.
Бизнес: `deposits_success_pct`, `bets_success_pct`, `kyc_pass_rate`.
Инфра: `cpu_util`, `cache_hit_ratio`, `cdn_waf_block_rate`.

3. 2 ეტიკეტები (მკაცრად შეზღუდული)

`region`, `tenant`, `environment`, `service`, `psp`, `bank_group`, `geo`, `device`, `version`, `component`.
აკრძალულია: 'userId', 'sessionID', ნედლეული ბარათების/დოკუმენტების ნომრები.

4) ვერსია და თავსებადობა

ძირითადი გზა: '/v1/metrics/... '; შეუთავსებელი ცვლილებები - მხოლოდ ახალ 'vX' - ში.
ეტიკეტების/ეპიზოდების დამატება არის backward compatible.
სემანტიკის შეცვლა - 'schema _ version' ველის მეშვეობით საპასუხოდ და გრეის პერიოდში.
სქემების კატალოგი ქვეყნდება, როგორც '/v1/schemas '.

5) Endpoints (REST, ანალოგიურად GRPC/GraphQL)

1. `GET /v1/metrics/query`

პარამეტრები

`metric` (multi), `from`, `to`, `step` (резолюция), `agg` (`avg|sum|min|max|p50|p95|p99`),

`filter[label]=value` (multi), `group_by=label1,label2`,

`downsample=1m|5m|1h`, `exemplars=true|false`, `limit` (рядов), `page`.

პასუხი: რიგების მასივი '{metric, labels {}, points: [[ts, value]], exemplars?'

2. `POST /v1/metrics/bulk-query`

სხეული: 50-მდე მოთხოვნა ერთი ბრძოლით. დაზოგავს მოთხოვნებს რთული დაშბორდებისთვის.

3. `GET /v1/metrics/instant`

მიმდინარე მნიშვნელობები 'ts' (ან „ახლა“) დროს მოცემული ფილტრებით.

4. `GET /v1/metrics/catalog`

ხელმისაწვდომი მეტრიკის, აღწერილობების, ეტიკეტების, დასაშვები აგრეგაციების, SLO სავალდებულო სია.

5. `GET /v1/metrics/health`

თავად API- ს მდგომარეობა: latency p95, ქეშის წინააღმდეგობა, ქეშის ჰიტების წილი.

6. `GET /v1/metrics/slo`

მზა SLO ვუ: შეცდომების ბიუჯეტის მოხმარება, მიზნების სტატუსი.

6) შეკითხვის მაგალითები

6. 1 PSP- ზე ავტომობილების წარმატების წარმატება TR- ში, 1 - წუთიანი მაკიაჟი, p95:

GET /v1/metrics/query? metric=auth_success_rate&from=2025-11-01T13:00:00Z&to=2025-11-01T16:00:00Z&step=1m&agg=p95&filter[geo]=TR&group_by=psp&downsample=1m

6. 2 p99 „bet-settle“ რეგიონებში, ექსპლარებით (ტრეისის მაგალითები):

GET /v1/metrics/query? metric=bet_settle_p99_ms&from=...&to=...&step=5m&group_by=region&exemplars=true

6. 3 EU დეპოზიტების SLO მყისიერი სტატუსი:

GET /v1/metrics/slo? domain=payments&region=EU&tenant=brandA

6. 4 Butch 3 მოთხოვნიდან (POST/bulk-query) - ერთი გრაფიკისთვის ფენებით.

7) დანაყოფები და წინსვლა

P50/p95/p99 P99 გამოითვლება TSDB/აგრეგატორის დონეზე; „downsample“ - სწორი კომპოზიციით (t-digest/HDR).
'group _ by' ნებადართულია მხოლოდ whitelisted ეტიკეტებით, რათა არ მოხდეს კარდინალობა.
'step' არის ვალუტა: მინიმუმ 10s რეალტიმისთვის, 1 მ საზოგადოებრივი დაშბორდებისთვის.

8) Cash, downsampling და სიახლე

მრავალ დონის ქეში: სამახსოვრო (30-60 წმ-მდე), განაწილებული (5 წუთამდე), CDN საზოგადოებრივი SLO ვისთვის.
Downsampling: მანქანა დიდი ფანჯრებით ('> 24h') - 5 მ/1 სთ წერტილი.
Freshness-заголовки: `X-Data-Freshness: 12s`, `X-Downsample: 1m`, `X-Partial: true|false`.

9) მულტფილმები და იზოლაცია

თითოეული მოთხოვნა უნდა შეიცავდეს 'tenant' (ტოკენში/ეტიკეტებში).
ABAC/RBAC: როლი/პოლიტიკა ზღუდავს წვდომას 'tenant, region, environment, metric _ id'.
Show/charge-back: სათაურები 'X-Query-Cost-Estimate' და usage მრიცხველები.

10) ავთენტიფიკაცია და უსაფრთხოება

OAuth2 mTLS/მომსახურების ნიშნები სკოპის შეზღუდვით.
SoD: მარეგულირებელი რისკების მქონე მეტრიკებზე წვდომა (ფინანსები, RG) - ცალკეული როლები.
Rate limits: კლიენტის გასაღები და 'metric _ id'.
PII გაფორმება: სერვერი ხელმძღვანელობს აკრძალული ფილტრების/ეტიკეტების არარსებობას.

11) გეო-რეზიდენცია და შესაბამისობა

მონაცემები იკითხება რეგიონალური მოთხრობებიდან (EU/LATAM/APAC) რეზიდენციის პოლიტიკის შესახებ.
ჯვარედინი რეგიონალური მოთხოვნები - მხოლოდ აგრეგატებისთვის PII- ის გარეშე და „კომპლექსის _ სკოპის“ თანდასწრებით.

12) ასლები/ექსპლარები და კორელაცია

„exemplars = true“ საპასუხოდ, percentiles წერტილებში, ბმულები ბრუნდება რამდენიმე წარმომადგენლობითი „trace _ id“ (PII გარეშე) სწრაფი RCA- სთვის.
კორელაცია: 'correlation _ id' ხელმისაწვდომია მეტამონაცემებში.

13) SLA API და შეცდომები

SLA პასუხი: p95-300 ms (ქეში), 1 ევრო. 5 გვ (ცივი ბილიკი), ხელმისაწვდომობა 99. 9%.

• '400' - შეუქცევადი მოთხოვნა (ძალიან ბევრი 'ჯგუფი _ by', ცუდი 'ნაბიჯი "),
• '403' - საკმარისი უფლებები/ტენანტი,
• „409“ - სქემების კონფლიქტი,
• '429' - კვოტა/რეიტინგის ლიმიტი,
• '502/504' - storaj დეგრადაცია (სათაურებში - რეკომენდაციები downsample/step),
• '206' - ნაწილობრივი პასუხი (ხუმრობის ნაწილი მიუწვდომელია).
• დიაგნოზის სათაურები: 'X-Query-Plan', 'X-Query-Cache', 'X-Query-Shards', 'X-RateLimit-Remaining'.

14) კვოტები, Rate limites და backpressure

სტანდარტულად: 10 rps თითო კლიენტზე, 50 ეპიზოდი პასუხზე, ფანჯარა 3 საათის განმავლობაში, 'step' 10c '.
Burst ნიშნები: დიდ ეკრანზე დაშბორდებისთვის, კოორდინირებული ფანჯრები.
Backpressure: სერვერს შეუძლია დააბრუნოს 'Retry-After', ურჩია გაზარდოს 'ნაბიჯი '/ჩართვა' downsample '.

15) SDK და საუკეთესო პრაქტიკა

SDK: Typescript/Go/Python. სტანდარტულად: აგრესიული ქეში, ექსპონენციალური backoff, 'If-None-Match'.

• შეამოწმეთ მოთხოვნები '/bulk-query 'საშუალებით;
• გამოიყენეთ 'ჯგუფი _ by' ეკონომიურად;
• ისტორიული მიმოხილვებისთვის - 'downsample = 1h';
• დაამატეთ დრო 2 წამი და 'cancellation' tocens.

15. 1 მინი მაგალითი (TS)

ts const res = await client. query({
metric: ["auth_success_rate"],
from: "-3h", to: "now", step: "1m",
agg: "p95",
filter: { geo: "TR", tenant: "brandA" },
group_by: ["psp"],
downsample: "1m",
exemplars: true,
timeoutMs: 1800
});

16) API მეტრიკის დაკვირვება

SLI самого API: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
KPI გამოყენება: rps, პასუხის საშუალო მოცულობა, ღირებულებით ტოპ მეტრიკა.
ალერტები: შეცდომების შეცდომები, '429' ზრდა, კაჩე-ჰიტის ვარდნა <სამიზნე.
ლოგოები: სტრუქტურირებული, PII; 'tenant', 'metric _ id', 'query _ cost _ class'.

17) FinOps პოლიტიკა

შეკითხვის კლასები: A (რეალითი დაშბორდები), B (ოპერაციული), C (ანალიტიკა). სხვადასხვა კვოტები/TTL.
ღირებულება: $/GB კითხვა ,/მოთხოვნა ,/გრაფიკი. ყოველთვიური ანგარიში „მძიმე“ მეტრიკებისა და ეტიკეტების შესახებ.
ოპტიმიზაცია: სერვერის მერგი, პრე-აგენტები პოპულარული SLO-VI, ავტომობილების რჩევა კლიენტისთვის (suggested 'step/downsample').

18) ინტეგრაცია

სტატუსის გვერდი: კითხულობს მზა SLO-wiew.
ალერტინგი: წესები ეყრდნობა '/slo 'და' instant '.
ინციდენტი-ბოტი: გრაფიკების/ნაჭრების სწრაფი სიპეტები მოკლე პრესეტების საშუალებით.
Workflow/Release-gates: გამოშვებების ბლოკი წითელ SLO- ში.

19) განხორციელების გზის რუკა (6-10 კვირა)

ნვე. 1-2: მეტრიკის კატალოგი, whitelists ეტიკეტები, სქემები '/catalog ', პროტოტიპი '/query' ქეში და downsample.
ნვე. 3-4: '/bulk-query ', '/slo', exemplars, RBAC/ABAC, კვოტები/Rhit-limes.
ნვე. 5-6: Geo-Sharding, CDN საზოგადოებრივი ტირაჟისთვის, FinOps სათაურები, SLI API dashbord.
ნვე. 7-8: SDK (TS/Go/Py), რეკომენდაციები/მოთხოვნის ლინტერი, კანარის ტესტები.
ნვე. 9-10: ქაოსი (შარდების/ქეშების უარყოფა), ღირებულების ოპტიმიზაცია, დეპრესიის პოლიტიკა.

20) არტეფაქტები

Metric Catalog: id, ერთეული, აღწერილობები ხელმისაწვდომია 'agg', დასაშვები ეტიკეტები.
Access Policy: როლები, სფეროები, ლიმიტები, SoD.
Query Style Guide: სწორი/არასწორი მოთხოვნების მაგალითები.
SLO Map: SLI შესაბამისობა საჯარო მიზნებს.
Cost Report: ძვირადღირებული მოთხოვნა/ეტიკეტები, ოპტიმიზაციის გეგმა.

21) KPI/KRI API მეტრიკა

p95/99 latency, error rate, partial responses.
Cache hit ratio და დანაზოგი CPU/IO.
საშუალო პასუხი და $/მოთხოვნა.
Dashbords- ის წილი გადავიდა '/bulk-query '.
ინციდენტები მაღალი კარდინალობის მოთხოვნების გამო.

22) ანტიპატერები

უფასო „ჯგუფი _ by“ ათეულობით ეტიკეტზე არის რადიკალური აფეთქება.
მათ შეაფასეს, „დაკეცილი“ კლიენტზე დამახინჯების შესახებ.
30-90 დღის მოთხოვნა downsample- ის გარეშე ძვირი და ნელია.
ტენანტების/რეგიონების ნაზავი ერთ პასუხში ავტორიზაციის გარეშე.
საჯარო პანელები ქეშის გარეშე/CDN.
მეტრიკის სემანტიკის ცვლილება 'vX' და გრეის პერიოდის გარეშე.

შედეგი

API მეტრული ოპერაციების API არის სტაბილური, უსაფრთხო და ეკონომიური კითხვის ფენა ტელემეტრიაზე: სტანდარტიზებული სქემები და ფასიანი სქემები, ქეში და downsampling, მკაცრი ეტიკეტები და წვდომა, SLO VI და exemplars RCA- სთვის, გამჭვირვალე SLLLA A A A A A - სთვის და ღირებულება. ასეთი ფენა საშუალებას გაძლევთ შექმნათ საიმედო დაშბორდები, ალერტინგი, სტატუსის კომუნიკაცია და გამოშვების კარიბჭეები, კონფიდენციალურობის, ბიუჯეტის და პროდუქტიულობის რისკის გარეშე.