Operation Metrics API'si

1) Amaç ve sorumluluk alanı

• Tutarlı SLI/SLO (giriş, para yatırma, oran, para çekme);
• KRI (erken risk göstergeleri: PSP/KYC/kuyruklar/replikasyonlar);
• İş ölçütleri (GEO/PSP/banka yetkilerinin başarısı, başarılı bahislerin payı, p95/p99 anahtar yol süreleri);
• gösterge panoları, uyarı, durum sayfaları, raporlama için güvenli, ucuz ve öngörülebilir okumalar.

2) Mimari ilkeler

Okuma ağırlıklı, yazma az: API yalnızca TSDB/önbellekten toplamaları okur.
SLO-ilk: yanıtlar zaman içinde tahmin edilebilir; Hatalar ve bozulma - şeffaf bir şekilde işaret edilir.
Maliyet farkındalığı: altörnekleme, kotalar, SDK'daki kanarya özellikleri.
Tasarıma göre gizlilik: Meta veri/etiketlerde PII yok; Jetonlar, geo-gate, SoD.
Çok kiracılı: marka/bölge/çevreye göre izolasyon.

3) Veri modeli (yüzey)

Metrik serisi = 'metrik _ id' + 'etiketler {}' + 'zaman damgası' + 'değer' (+ isteğe bağlı 'örnek {trace _ id =...}').

3. 1 Kategoriler

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 Etiketler (Kesinlikle Sınırlı)

'region', 'tenant', 'environment', 'service', 'psp', 'bank _ group', 'geo', 'device', 'version', 'component'.
Yasak: 'UserId', 'sessionId', ham kart/belge numaraları.

4) Sürüm oluşturma ve uyumluluk

Temel yol:'/v1/metrics/... '; Uyumsuz değişiklikler - sadece yeni 'vX'de.
Etiket/seri ekleme - geriye dönük uyumlu.
Semantik değişim, yanıt ve ödemesiz dönemdeki 'schema _ version' alanından geçer.
Şema dizini'/v1/schemas'olarak yayınlanır.

5) Uç noktalar (REST, gRPC/GraphQL'de benzer)

1. 'GET/v1/metrics/query'

• 'metrik' (çoklu), ',' dan ',', 'adım' (резолюция), 'agg' ('avg' sum'min 'max' p50 | p95 | p99 '),
• 'filter [label] = value' (multi), 'group _ by = label1, label2',
• 'dewnsample = 1m | 5m | 1h', 'exemplars = true' false ',' limit '(рядов),' page '.
• Cevap: seri dizisi '{metrik, etiketler {}, noktalar: [[ts, değer]], örnekler?}'.

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

Gövde: Bir grupta 50 isteğe kadar. Karmaşık panolar için istekleri kaydeder.

3. 'GET/v1/metrics/instant'

Belirtilen filtrelerle 'ts' (veya'şimdi ') değerlerindeki geçerli değerler.

4. 'GET/v1/metrics/catalog'

Kullanılabilir metriklerin, açıklamaların, etiketlerin, izin verilen toplamaların, SLO bağlamalarının listesi.

5. 'GET/v1/metrics/health'

API'nin kendisinin durumu: gecikme p95, önbellek esnekliği, önbellek isabetlerinin paylaşımı.

6. 'GET/v1/metrics/slo'

Hazır SLO görünümleri: hata bütçesinin tüketimi (hızlı/yavaş), hedef durumları.

6) Örnek istekleri

6. 1 TR'deki PSP yetkilendirmelerinin başarısı, 1 dakikalık ızgara, 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" bölgelere göre, örneklerle (eser örnekleri):

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

6. 3 AB anlık mevduat SLO durumu:

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

6. 4 Toplu 3 sorgu (POST/toplu sorgu) - katmanlarla bir grafik için.

7) Toplamlar ve yüzdelik dilimler

P50/p95/p99 yüzdelik dilimleri TSDB/toplayıcı düzeyinde hesaplanır; 'downsample'ile - doğru kompozisyon ile (t-digest/HDR).
'group _ by', yalnızca beyaz listeye alınmış etiketlerde, kardinaliteyi havaya uçurmamak için izin verilir.
'adım' doğrulandı: Gerçek zamanlı olarak en az 10, genel panolar için 1 m.

8) Nakit, altörnekleme ve tazelik

Çok düzeyli önbellek: Bellek içi (30-60 saniyeye kadar), dağıtılmış (5 dakikaya kadar), genel SLO görünümleri için CDN.
Altörnekleme: büyük pencereli otomatik ('> 24 saat') - 5m/1h puan.
Freshness- заголовки: 'X-Data-Freshness: 12s', 'X-Downsample: 1m', 'X-Partial: true' false '.

9) Çok kiracı ve izolasyon

Her istek 'kiracı' içermelidir (belirteç/etiketlerde).
ABAC/RBAC: rol/politika, 'müşteri, bölge, çevre, metric_id' tarafından erişimi kısıtlar.
Show/charge-back: 'X-Query-Cost-Estimate' başlıkları ve kullanım sayaçları.

10) Kimlik doğrulama ve güvenlik

OAuth2 mTLS/kapsam servis belirteçleri.
SoD: Olası düzenleyici riskleri olan metriklere erişim (finans, RG) - bireysel roller.
Hız sınırları: istemci anahtarı ve 'metric _ id'ile.
PII sanitasyonu: Sunucu, yasaklanmış filtrelerin/etiketlerin yokluğunu doğrular.

11) Geo-Residency ve Uyum

Veriler, ikamet politikasına ilişkin bölgesel depolardan (EU/LATAM/APAC) okunur.
Bölgeler arası sorgular - yalnızca PII içermeyen ve 'compliance _ scope' içeren kümeler için.

12) Örnekler ve korelasyon

'exemplars = true'ile, yüzdelik noktalardaki yanıt, hızlı RCA için bir çift temsili' trace _ id '(PII olmadan) referansını döndürür.
Korelasyon: 'correlation _ id' yanıt meta verilerinde mevcuttur.

13) SLA API ve hatalar

Yanıt SLA: p95 ≤ 300 ms (önbellek), ≤ 1. 5 s (soğuk yol), kullanılabilirlik ≥ 99. 9%.

• '400' - geçersiz istek (çok fazla 'group _ by', kötü 'step'),
• '403' - yetersiz haklar/kiracı,
• '409' - devre çakışması,
• '429' - kota/oran sınırı,
• '502/504' - depolamanın bozulması (başlıklarda - alt örnek/adım için öneriler),
• '206' kısmi bir cevaptır (bazı parçalar mevcut değildir).
• Tanılama başlıkları: 'X-Query-Plan', 'X-Query-Cache', 'X-Query-Shards', 'X-RateLimit-Remaining'.

14) Kotalar, oran limitleri ve geri basınç

Varsayılan: İstemci başına 10 rps, yanıt başına 50 bölüm, 3 saatlik pencere, 'adım ≥ 10c'.
Burst belirteçleri: büyük ekrana panolar için, koordine pencereler.
Backpressure: sunucu 'Retry-After' döndürebilir, 'step' artırmak/' downsample 'etkinleştirmek için tavsiye.

15) SDK ve en iyi uygulamalar

SDK: Typescript/Go/Python. Varsayılan: agresif önbellek, üstel geri kapanma, 'If-None-Match'.

• Grup sorguları'/bulk-query'tarafından;
• 'group _ by'ı idareli kullanın;
• Tarihsel incelemeler için - 'downsample = 1h';
• 2 saniye ≤ zaman aşımları ve 'iptal' belirteçleri ekleyin.

15. 1 Mini Örnek (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 metriklerinin gözlemlenebilirliği

SLI самого API: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
Kullanım KPI: rps, ortalama yanıt hacmi, en yüksek maliyet metrikleri.
Uyarılar: Hatalarda yanma oranı, spike '429', drop cache-hit <target.
Günlükler: yapılandırılmış, PII olmadan; 'tenant', 'metric _ id', 'query _ cost _ class'.

17) FinOps politikaları

İstek sınıfları: A (gerçek zamanlı gösterge panoları), B (operasyonel), C (analitik). Farklı kotalar/TTL.
Maliyet: $/GB okur, $/istek, $/grafik. "Ağır" metrikler ve etiketler hakkında aylık rapor.
Optimizasyonlar: sunucu birleştirme, popüler SLO görünümü için ön toplama, istemciye otomatik ipuçları (önerilen 'adım/alt örnek').

18) Entegrasyonlar

Durum sayfası: Hazır SLO görünümlerini okur.
Uyarı: kurallar'/slo've 'instant'a dayanır.
Incident-bot: Kısa hazır ayarlar aracılığıyla hızlı grafik/dilim parçacıkları.
İş akışı/Release-gates: kırmızı SLO'larda serbest bırakma bloğu.

19) Uygulama Yol Haritası (6-10 hafta)

Ned. 1-2: metrics catalog, label whitelists,'/catalog 'schemas,'/query' prototype with cache ve downsample.
Ned. 3-4:'/bulk-query ','/slo', örnekler, RBAC/ABAC, kotalar/oran limitleri.
Ned. 5-6: geo-sharding, genel görünüm için CDN, FinOps başlıkları, SLI API panosu.
Ned. 7-8: SDK (TS/Go/Py), öneriler/sorgu linter, kanarya testleri.
Ned. 9-10: kaos öğretileri (parça/önbellek hatası), değer optimizasyonu, amortisman politikası.

20) Eserler

Metrik Katalog: id, birimler, açıklamalar, mevcut 'agg', geçerli etiketler.
Erişim Politikası: roller, alanlar, sınırlar, SoD.
Sorgu Stili Kılavuzu - doğru/yanlış sorguların örnekleri.
SLO Haritası: SLI uyumluluğu ↔ kamu hedefleri.
Maliyet Raporu: en pahalı sorgular/etiketler, optimizasyon planı.

21) KPI/KRI API Metrikleri

P95/99 gecikme, hata oranı, kısmi yanıtlar.
Önbellek isabet oranı ve CPU/IO tasarrufu.
Ortalama yanıt boyutu ve $/request.
'/bulk-query'ye geçen panoların oranı.
Yüksek kardinalite talepleri nedeniyle meydana gelen olaylar.

22) Antipatterns

Düzinelerce işaretle özgür'grup _ by '- bir kardinalite patlaması.
Percentiles istemci üzerinde "katlanmış" - bozulmalar.
Downsample olmadan 30-90 gün için talepler - pahalı ve yavaş.
Kiracıların/bölgelerin izinsiz olarak tek bir yanıtta karıştırılması.
Önbellek/CDN içermeyen genel paneller.
'vX've grace periyodu olmadan metriklerin semantiğini değiştirme.

Toplam

Operasyon metrikleri API'si, telemetri üzerinden istikrarlı, güvenli ve uygun maliyetli bir okuma katmanıdır: standartlaştırılmış şemalar ve yüzdelikler, önbellek ve altörnekleme, katı etiketler ve erişimler, SLO görünümü ve RCA, şeffaf SLA'lar ve maliyet için örnekler. Bu katman, gizlilik, bütçe ve performans riski olmadan güvenilir panolar, uyarılar, durum iletişimleri ve serbest bırakma kapıları oluşturmanıza olanak tanır.