API für Betriebskennzahlen

1) Zweck und Aufgabenbereich

• konsistente SLI/SLO (Login, Einzahlung, Wette, Ausgabe);
• KRI (frühe Risikoindikatoren: PSP/KYC/Warteschlangen/Replikation);
• Geschäftsmetriken (Erfolg der GEO/PSP/Bankberechtigungen, Anteil der erfolgreichen Wetten, p95/p99 der Dauer der Schlüsselpfade);
• sichere, günstige und vorhersehbare Lesungen für Dashboards, Alerting, Statusseiten, Reporting.

2) Architektonische Prinzipien

Read-heavy, write-few: Die API liest nur Aggregationen aus dem TSDB/Cache.
SLO-first: Antworten sind zeitlich vorhersehbar; Fehler und Degradationen - transparent signalisiert.
Kosten: Downsampling, Quoten, Kanarienvögel im SDK.
Privacy-by-Design: keine PII in Metadaten/Labels; Token, Geo-Gate, SoD.
Multi-tenant: Isolation nach Marke/Region/Umgebung.

3) Datenmodell (oberflächlich)

Eine Reihe von Metriken = 'metric _ id' + 'labels {}' + 'timestamp' + 'value' (+ optional 'exemplar {trace _ id =...}').

3. 1 Kategorien

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 Labels (streng limitiert)

`region`, `tenant`, `environment`, `service`, `psp`, `bank_group`, `geo`, `device`, `version`, `component`.
Verboten: 'userId', 'sessionId', Rohkarten-/Dokumentennummern.

4) Versionierung und Kompatibilität

Basispfad: „/v1/metrics/... “; inkompatible Änderungen - nur im neuen 'vX'.
Hinzufügen von Labels/Serien - backward-compatible.
Änderung der Semantik - durch das Feld 'schema _ version' in der Antwort und grace-Periode.
Das Schema-Verzeichnis wird als '/v1/schemas' veröffentlicht.

5) Endpunkte (REST, ähnlich in 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`.
• Antwort: Array von Reihen'{metric, Etiketten {}, Punkte: [[ts, Wert]], Beispiele?}'.

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

Body: bis zu 50 Anfragen pro Batch. Spart Anfragen für komplexe Dashboards.

3. `GET /v1/metrics/instant`

Aktuelle Werte zum Zeitpunkt 'ts' (oder „jetzt“) mit den angegebenen Filtern.

4. `GET /v1/metrics/catalog`

Liste der verfügbaren Metriken, Beschreibungen, Labels, zulässige Aggregationen, SLO-Bindungen.

5. `GET /v1/metrics/health`

Status der API selbst: Latenz p95, Cache-Fehlertoleranz, Anteil der Cache-Treffer.

6. `GET /v1/metrics/slo`

Fertige SLO-Ansichten: Fehlerbudget-Ausgaben (schnell/langsam), Zielstatus.

6) Beispiele für Anfragen

6. 1 Erfolg der PSP-Autorisierungen in TR, 1-min grid, 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“ nach Regionen, mit Beispielen (Trace-Beispiele):

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

6. 3 Sofortstatus von SLO-Einlagen nach EU:

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

6. 4 Batch von 3 Abfragen (POST/bulk-query) - für einen Graphen mit Ebenen.

7) Aggregationen und Perzentile

Die Perzentile p50/p95/p99 werden auf der Ebene TSDB/Aggregator berechnet; bei 'downsample' - mit korrekter Zusammensetzung (t-digest/HDR).
'group _ by' ist nur über whitelisted-Labels erlaubt, um die Kardinalität nicht zu sprengen.
'step' ist validiert: mindestens 10s für Echtzeit, 1m für öffentliche Dashboards.

8) Cache, Downsampling und Frische

Mehrstufiger Cache: In-Memory (bis zu 30-60 s), verteilt (bis zu 5 min), CDN für öffentliche SLO-Views.
Downsampling: Automatik bei großen Fenstern ('> 24h') → 5m/1h Punkt.
Freshness-заголовки: `X-Data-Freshness: 12s`, `X-Downsample: 1m`, `X-Partial: true|false`.

9) Multi-Tenant und Isolierung

Jede Anfrage muss' tenant'(in Token/Labels) enthalten.
ABAC/RBAC: Rolle/Politik beschränkt den Zugriff auf 'tenant, region, Umwelt, metric_id'.
Show/Charge-Back: Überschriften 'X-Query-Cost-Estimate' und Nutzungszähler.

10) Authentifizierung und Sicherheit

OAuth2 mTLS/Service-Token mit Scope-Beschränkung.
SoD: Zugang zu Metriken mit möglichen regulatorischen Risiken (Finanzen, RG) - Einzelrollen.
Rate limits: nach Kundenschlüssel und nach 'metric _ id'.
PII-Desinfektion: Der Server validiert das Fehlen verbotener Filter/Labels.

11) Geo-Residenz und Compliance

Die Daten sind aus den Regionalversammlungen (EU/LATAM/APAC) zur Aufenthaltspolitik zu lesen.
Regional übergreifende Abfragen - nur für Aggregate ohne PII und mit 'compliance _ scope'.

12) Instanzen/Beispiele und Korrelation

Bei 'exemplars = true' werden in der Antwort an den Perzentilpunkten Verweise auf ein Paar repräsentativer 'trace _ id' (ohne PII) für eine schnelle RCA zurückgegeben.
Korrelation: 'correlation _ id' ist in den Metadaten der Antwort verfügbar.

13) SLA API und Fehler

Antwort SLA: p95 ≤ 300 ms (Cache), ≤ 1. 5 s (kalter Weg), Verfügbarkeit ≥ 99. 9%.

• „400“ ist eine ungültige Abfrage (zu viel „group _ by“, schlechtes „step“),
• „403“ - unzureichende Rechte/Tenant,
• „409“ - der Konflikt zwischen den Regelungen,
• „429“ - Quote/Rate-Limit,
• „502/504“ - Degradation des Torax (in den Überschriften - Empfehlungen für Downsample/Step),
• '206' ist eine partielle Antwort (ein Teil der Shards ist nicht verfügbar).
• Diagnoseköpfe: „X-Query-Plan“, „X-Query-Cache“, „X-Query-Shards“, „X-RateLimit-Remaining“.

14) Quoten, Rate Limits und Backpressure

Standard: 10 rps pro Client, 50 Folgen pro Antwort, 3-Stunden-Fenster, 'step ≥ 10c'.
Burst-Token: für Dashboards auf dem großen Bildschirm, konsistente Fenster.
Backpressure: Der Server kann 'Retry-After' zurückgeben, indem er rät, 'step' zu erhöhen/' Downsample' einzuschalten.

15) SDK und Best Practices

SDK: Typescript/Go/Python. Standard: aggressiver Cache, exponentieller Backoff, 'If-None-Match'.

• Gruppieren von Abfragen über '/bulk-query';
• 'group _ by' sparsam verwenden;
• für historische Übersichten: „downsample = 1h“;
• Timeouts ≤ 2 s und 'cancellation' -Token hinzufügen.

15. 1 Mini-Beispiel (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-Beobachtbarkeit von Metriken

SLI самого API: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
KPIs der Nutzung: rps, durchschnittliches Antwortvolumen, Top-Metriken zu den Kosten.
Alerts: Burn-Rate für Fehler, Splash '429', Drop Cache-Hit <Ziel.
Protokolle: strukturiert, ohne PII; 'tenant', 'metric _ id', 'query _ cost _ class'.

17) FinOps-Richtlinien

Anforderungsklassen: A (Echtzeit-Dashboards), B (operativ), C (Analytics). Unterschiedliche Quoten/TTL.
Kosten: $/GB Lesen, $/Anfrage, $/graph. Monatlicher Bericht über „schwere“ Metriken und Labels.
Optimierungen: Server-Merge, Voraggregate für beliebte SLO-Views, Auto-Tipps für den Kunden (suggested 'step/downsample').

18) Integration

Status-Seite: liest fertige SLO-Views.
Alerting: Die Regeln basieren auf '/slo 'und' instant'.
Incident-Bot: Schnelle Schnipsel von Charts/Slices durch kurze Presets.
Workflow/Release-Gates: Block der Releases bei roten SLOs.

19) Umsetzungsfahrplan (6-10 Wochen)

Ned. 1-2: Metrikkatalog, Whitelists der Labels, Schemata '/catalog', Prototyp '/query 'mit Cache und Downsample.
Ned. 3-4: „/bulk-query “, „/slo“, Beispiele, RBAC/ABAC, Quoten/Rate-Limits.
Ned. 5-6: Geo-Sharding, CDN für Public View, FinOps-Header, SLI API Dashboard.
Ned. 7-8: SDK (TS/Go/Py), Recommendations/Request Linter, Kanarientests.
Ned. 9-10: Chaos-Übungen (Shard/Cache-Fehler), Kostenoptimierung, Deprecate-Politik.

20) Artefakte

Metric Katalog: id, Einheiten, Beschreibungen, verfügbare' agg', gültige Labels.
Access Policy: Rollen, Bereiche, Grenzen, SoD.
Query Style Guide: Beispiele für richtige/falsche Abfragen.
SLO Map: SLI-Konformität ↔ öffentliche Ziele.
Kostenreport: Top teure Abfragen/Tags, Optimierungsplan.

21) KPI/KRI API Metriken

p95/99 latency, error rate, partial responses.
Cache-Trefferverhältnis und CPU/IO-Einsparungen.
Durchschnittliche Antwortgröße und $/Anfrage.
Der Anteil der Dashboards, die auf '/bulk-query 'umgestellt haben.
Vorfälle aufgrund von Anfragen hoher Kardinalität.

22) Antipatterns

Ein freies' group _ by 'durch Dutzende von Markierungen → eine Explosion der Kardinalität.
Perzentile, „gefaltet“ auf dem Client → Verzerrungen.
Anfragen für 30-90 Tage ohne Downsample → teuer und langsam.
Mischen von Tenanten/Regionen in einer einzigen Antwort ohne Autorisierung.
Öffentliche Panels ohne Cache/CDN.
Änderung der Semantik von Metriken ohne' vX 'und Grace-Periode.

Summe

Die Operations Metrics API ist eine stabile, sichere und kostengünstige Leseebene über der Telemetrie: standardisierte Schemata und Perzentile, Cache und Downsampling, strikte Labels und Zugriffe, SLO-Views und Exemplarien für RCA, transparente SLAs und Kosten. Mit einer solchen Schicht können Sie zuverlässige Dashboards, Alerting, Status-Kommunikation und Release-Gates erstellen, ohne die Privatsphäre, das Budget und die Leistung zu gefährden.