Operacja Metrics API

1) Cel i obszar odpowiedzialności

• spójne SLI/SLO (login, deposit, rate, withdrawal);
• KRI (wczesne wskaźniki ryzyka: PSP/KYC/kolejki/replikacje);
• wskaźniki biznesowe (sukces autoryzacji GEO/PSP/banku, udział udanych zakładów, p95/p99 kluczowych okresów trwania ścieżki);
• bezpieczne, tanie i przewidywalne odczyty dla desek rozdzielczych, ostrzeganie, strony stanu, raportowanie.

2) Zasady architektoniczne

Read-heavy, write-few: API czyta tylko agregacje z TSDB/cache.
SLO-first: odpowiedzi są przewidywalne w czasie; błędy i degradacja - są sygnalizowane w sposób przejrzysty.
Świadomość kosztów: obniżenie wartości, kwoty, cechy kanaryjskie w SDK.
Prywatność według projektu: brak PII w metadanych/etykietach; żetony, bramy geograficzne, SoD.
Multi-najemca: izolacja według marki/regionu/środowiska.

3) Model danych (powierzchnia)

Seria metryczna = 'metric _ id' +' labels {} '+' timestamp '+' value '(+ opcjonalny' exemplar {trace _ id =...} ').

3. 1 Kategorie

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'.
Миснеz: 'deposits _ success _ pct', 'bets _ success _ pct', 'kyc _ pass _ rate'.
Индра: 'cpu _ util', 'cache _ hit _ ratio', 'cdn _ waf _ block _ rate'.

3. 2 etykiety (ściśle ograniczone)

„region”, „najemca”, „środowisko”, „usługa”, „psp”, „bank _ group”, „geo”, „urządzenie”, „wersja”, „komponent”.
Zabronione: 'viaId',' Id', surowe numery kart/dokumentów.

4) Wersioning i kompatybilność

Ścieżka bazowa: '/v1/metrics/... '; niekompatybilne zmiany - tylko w nowym 'vX'.
Dodawanie etykiet/serii - kompatybilne wstecz.
Semantyka zmienia się poprzez 'schema _ version' field' w odpowiedzi i okresie łaski.
Katalog schematu jest publikowany jako '/v1/schemas '.

5) Punkty końcowe (REST, podobne w gRPC/GraphQL)

1. „GET/v1/metrics/query”

• 'metric' (multi), 'od', 'do', 'step' (револиса), 'agg' ('avg'sum'min'max'p50|p95|p99'),
• „filter [etykieta] = wartość” (multi), „group _ by = label1, label2”,
• 'downsample=1m|5m|1h', 'exemplars = true' false ',' limit '(рудой),' page '.
• Odpowiedź: tablica serii '{metric, labels {}, points: [[ts, value]], exemplars?}'.

2. „POST/v1/metrics/bulk-query”

Ciało: Do 50 wniosków w jednej partii. Zapisuje żądania złożonych desek rozdzielczych.

3. „GET/v1/metrics/instant”

Aktualne wartości w 'ts' (lub' teraz ') z określonymi filtrami.

4. "GET/v1/metrics/catalogs'

Lista dostępnych metryk, opisów, etykiet, dozwolonych agregacji, wiązań SLO.

5. „GET/v1/metrics/health”

Stan samego API: latency p95, odporność pamięci podręcznej, udział trafień w pamięci podręcznej.

6. „GET/v1/metrics/slo”

Gotowe widoki SLO: zużycie budżetu błędu (szybki/wolny), docelowe statusy.

6) Wnioski o próbkę

6. 1 Sukces autoryzacji PSP w TR, 1-min siatka, 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” według regionów, z przykładami (przykłady śladowe):

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

6. 3 Status EU instant deposit SLO:

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

6. 4 Partia 3 zapytań (POST/masowe zapytanie) - dla jednego wykresu z warstwami.

7) Agregacje i percentyle

Percentile p50/p95/p99 oblicza się na poziomie TSDB/agregatora; z „downsample” - o prawidłowym składzie (t-digest/HDR).
"grupa _ by 'jest dozwolona tylko na białych etykietach, aby nie wysadzać kardynalności.
„step” jest zatwierdzony: minimum 10 s dla czasu rzeczywistego, 1 m dla publicznych desek rozdzielczych.

8) Gotówka, upośledzenie i świeżość

Pamięć podręczna wielopoziomowa: pamięć (do 30-60 s), rozproszona (do 5 min), CDN dla publicznych widoków SLO.
Downsampling: automatyczne z dużymi oknami ('> 24h') → 5m/1h punktów.
Świeżość-маболовка: "X-Data-świeżość: 12s'," X-Downsample: 1m "," X-Partial: true 'false ".

9) Multi-najemca i izolacja

Każde żądanie musi zawierać „najemcę” (w tokenach/etykietach).
ABAC/RBAC: rola/polityka ogranicza dostęp najemcy, regionu, środowiska, metric_id'.
Pokaż/ładuj z powrotem: nagłówki „X-Query-Cost-Estimate” i liczniki użytkowania.

10) Uwierzytelnianie i bezpieczeństwo

OAuth2 mTLS/tokeny serwisowe.
SoD: dostęp do wskaźników o możliwym ryzyku regulacyjnym (finansowanie, RG) - indywidualne role.
Limity stawki: według klucza klienta i przez 'metric _ id'.
Sanitarność PII: serwer sprawdza brak zabronionych filtrów/etykiet.

11) Georezydencja i zgodność

Dane są odczytywane z magazynów regionalnych (EU/LATAM/APAC) na temat polityki rezydencji.
Zapytania międzyregionalne - tylko dla kruszyw bez PII i z „compliance _ scope”.

12) Instancje i korelacja

Przy 'exemplars = true' odpowiedź w punktach percentylowych zwraca odniesienia do pary reprezentatywnych 'trace _ id' (bez PII) dla szybkiego RCA.
Korelacja: 'correlation _ id' jest dostępna w metadanych odpowiedzi.

13) SLA API i błędy

Odpowiedź SLA: p95 ≤ 300 ms (pamięć podręczna), ≤ 1. 5 s (zimna ścieżka), dostępność ≥ 99. 9%.

• '400' - nieprawidłowe żądanie (zbyt dużo 'group _ by', źle 'krok'),
• „403” - niewystarczające prawa/najemca,
• „409” - konflikt obwodów,
• „429” - limit kwot/stawek,
• „502/504” - degradacja magazynu (w nagłówkach - zalecenia dotyczące downsample/step),
• „206” to częściowa reakcja (niektóre odłamki nie są dostępne).
• Nagłówki diagnostyczne: 'X-Query-Plan', 'X-Query-Cache', 'X-Query-Shards', 'X-Limit-Remaining'.

14) Kwoty, limity stawek i ciśnienie wsteczne

Domyślnie: 10 rps na klienta, 50 odcinków na odpowiedź, 3 godzinne okno, 'krok ≥ 10c'.
Żetony pęknięcia: dla desek rozdzielczych do dużego ekranu, koordynowane okna.
Backpressure: serwer może zwrócić 'Retry-After', zalecając zwiększenie 'step '/enable' downsample '.

15) SDK i najlepsze praktyki

SDK: maszynopis/Go/Python. Domyślnie: agresywny cache, wykładniczy backoff, 'If-None-Match'.

• zapytania grupowe przez '/zapytanie zbiorcze ';
• delikatnie używać „group _ by”;
• dla recenzji historycznych - „downsample = 1h”;
• dodać czas ≤ 2 sekundy i żetony „anulowania”.

15. 1 Mini Example (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) Obserwowalność wskaźników API

SLI самовсAPI: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
Użycie KPI: rps, średnia objętość odpowiedzi, najwyższe wskaźniki kosztów.
Alerty: wskaźnik oparzeń błędów, kolec '429', kropla cache-hit <target.
Kłody: ustrukturyzowane, bez PII; 'lokator', 'metric _ id',' query _ cost _ class '.

17) Polityka FinOps

Klasy żądań: A (deski rozdzielcze w czasie rzeczywistym), B (operacyjne), C (analityczne). Różne kwoty/TTL.
Koszt: $/GB odczytuje, $/żądanie, $/wykres. Miesięczny raport na temat „ciężkich” metryk i etykiet.
Optymalizacja: połączenie serwera, wstępne agregaty dla popularnego SLO-view, automatyczne wskazówki dla klienta (sugerowane 'step/downsample').

18) Integracja

Strona stanu: Odczytuje gotowe widoki SLO.
Ostrzeganie: zasady polegają na '/slo'i 'instant'.
Incydent-bot: szybkie kije wykresów/plasterków przez krótkie ustawienia wstępne.
Workflow/Release-gates: blok uwalniania w czerwonych SLO.

19) Plan realizacji (6-10 tygodni)

Ned. 1-2: katalog metryki, białe etykiety, schematy '/katalog ', prototyp '/zapytanie' z pamięcią podręczną i downsample.
Ned. 3-4: „/zapytanie zbiorcze ”, „/slo”, przykłady, RBAC/ABAC, limity kwot/stawek.
Ned. 5-6: geowłóknina, CDN dla widoku publicznego, nagłówki FinOps, deska rozdzielcza SLI API.
Ned. 7-8: SDK (TS/Go/Py), zalecenia/linter zapytania, testy kanarkowe.
Ned. 9-10: nauki chaosu (odłamek/awaria pamięci podręcznej), optymalizacja wartości, polityka deprecjacji.

20) Artefakty

Katalog metryczny: id, jednostki, opisy, dostępne 'agg', ważne etykiety.
Polityka dostępu: role, obszary, limity, SoD.
Przewodnik po stylu zapytania - przykłady poprawnych/nieprawidłowych zapytań.
Mapa SLO: Cele publiczne w zakresie zgodności z SLI.
Raport kosztów: top drogie zapytania/tagi, plan optymalizacji.

21) KPI/KRI API Metrics

p95/99 opóźnienia, częstość błędów, częściowe odpowiedzi.
Współczynnik trafienia pamięci podręcznej i oszczędności procesora/IO.
Średni rozmiar odpowiedzi i $/request.
Proporcja desek rozdzielczych, które przełączyły się na '/zapytanie luzem '.
Incydenty spowodowane prośbami o wysoką kardynalność.

22) Antypattery

Wolny 'group _ by' przez dziesiątki znaków → eksplozja kardynalności.
Percentyle „złożone” na klienta → zniekształcenia.
Prośby na 30-90 dni bez downsample → drogie i powolne.
Mieszanie najemców/regionów w jednej odpowiedzi bez zezwolenia.
Panele publiczne bez pamięci podręcznej/CDN.
Zmiana semantyki metryki bez 'vX' i okresu łaski.

Razem

Mierniki operacyjne API to stabilna, bezpieczna i opłacalna warstwa odczytu przez telemetrię: znormalizowane schematy i percentyle, pamięć podręczna i downsampling, ścisłe etykiety i dostęp, widok SLO i przykłady dla RCA, przejrzyste SLA i koszty. Ta warstwa pozwala na budowanie niezawodnych desek rozdzielczych, alarmów, komunikatów statusowych i bram uwalniania bez ryzyka prywatności, budżetu i wydajności.