API metriche di operazioni

1) Assegnazione e area di responsabilità

• SLI/SLO consistenti (login, deposito, tasso, conclusione);
• KRI (primi indicatori di rischio: PSP/KYC/code/replica);
• metriche aziendali (successo delle autorizzazioni GEO/PSP/banche, tasso di successo, p95/p99 lunghezze di percorsi chiave);
• letture sicure e prevedibili per dashboard, alerting, status page, report.

2) Principi architettonici

Read-heavy, write-few: l'API legge solo le aggregazioni da TSDB/cache.
SLO-first: le risposte sono prevedibili nel tempo; errori e degrado sono segnalati in modo trasparente.
Cost-aware: downsampling, quote, filetti canari in SDK.
Privacy-by-design: niente PII nei metadati/etichette; token, geo-gate, SoD.
Multi-tenant: isolamento per marchio/regione/ambiente.

3) Modello di dati (cosmetico)

Serie di metriche = 'metric _ id' + 'labels {}' + 'timestamp' + 'value' (+ opzionale'execuplar {trace _ id =...} ').

3. 1 Categorie

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 Etichette (rigorosamente limitate)

`region`, `tenant`, `environment`, `service`, `psp`, `bank_group`, `geo`, `device`, `version`, `component`.
Vietato: «userId», «sessionId», numeri crudi di carte e documenti.

4) Versioning e compatibilità

Percorso di base: '/v1/metrics/... '; cambiamenti incompatibili solo nel nuovo «vX».
Aggiunge etichette/serie - backward-compatibile.
Cambia semantica attraverso il campo «schema _ version» nella risposta e il periodo grace.
La directory degli schemi viene pubblicata comè/v1/schemas ".

5) Endpoint (REST, simile al 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`.
• Risposta: array di serie '{metric, labels {}, punti: [[[ts, value]], exemplars?}'.

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

Corpo: fino a 50 richieste con un battello. Risparmia le richieste per i dashboard complessi.

3. `GET /v1/metrics/instant`

Valori correnti al momento «ts» (o «ora») con filtri specificati.

4. `GET /v1/metrics/catalog`

Elenca le metriche, le descrizioni, le etichette, le aggregazioni valide, i riferimenti SLO disponibili.

5. `GET /v1/metrics/health`

Lo stato dell'API stessa è latency p95, la disponibilità della cache e la percentuale di hit.

6. `GET /v1/metrics/slo`

Cloud SLO-View: budget di errore (fast/slow), stato degli obiettivi.

6) Esempi di query

6. 1 Successo delle autorizzazioni PSP in TR, grid da 1 min, 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» per regione, con exemplars (esempi di trace):

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

6. 3 Stato immediato dei depositi SLO su EU:

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

6. 4 Batch su 3 query (POST/bulk-query) - Per un singolo grafico con livelli.

7) Aggregazioni e percense

I Percentili p50/p95/p99 sono calcolati a livello TSDB/aggregatore; «downsample» è una composizione corretta (t-digest/HDR).
«group _ by» è consentito solo dalle etichette whitelisted per non far esplodere la cardinalità.
«step» è valida: minimo 10 s per realtime, 1m per dashboard pubblici.

8) Cache, downsampling e freschezza

Cache su più livelli: in-memory (fino a 30-60 s), distribuita (fino a 5 min), CDN per le viste SLO pubbliche.
Il Downsampling è un distributore automatico a grandi finestre ('> 24h') di punti 5m/1h.
Freshness-заголовки: `X-Data-Freshness: 12s`, `X-Downsample: 1m`, `X-Partial: true|false`.

9) Multi-tenente e isolamento

Ogni richiesta deve contenere «tenant» (in token/etichette).
ABAC/RBAC: ruolo/criterio limita l'accesso a «tenant, region, environment, metric _ id».
Show/force-back - Intestazioni «X-Query-Cost-Estimate» e contatori usage.

10) Autenticazione e sicurezza

OAuth2 mTLS/token di servizio con limitazione scope.
SoD Accesso alle metriche con possibili rischi regolatori (finanza, RG) - ruoli separati.
Rate limits: per chiave client e per «metric _ id».
Igiene PII: il server valuta l'assenza di filtri/etichette proibiti.

11) Geo residenza e compagine

I dati vengono letti dagli store regionali (EU/LATAM/APAC) sulla politica di residenza.
Richieste crocifisse - Solo per aggregazioni prive di PII e con «compliance _ scope».

12) Varianti/Exemplars e correlazione

Con «exemplars = true», i punti dei percettori restituiscono i riferimenti alla coppia «trace _ id» rappresentativa (senza PII) per RCA veloce.
Correlazione: 'correlation _ id', disponibile nei metadati della risposta.

13) API SLA e errori

Risposta SLA: p95-300 ms (cache), 1. 5 c (via fredda), disponibilità ≥ 99. 9%.

• «400» è una richiesta non calda (troppo «group _ by», cattivo «step»),
• '403' - non abbastanza diritti/tenente,
• «409» - conflitto di schemi,
• «429» - quota/rate-limite,
• '502/504' - Degrado dello story (i titoli includono suggerimenti per downsample/step),
• «206» è una risposta parziale (parte dei sardi non sono disponibili).
• I titoli di diagnostica sono: X-Query-Plan, X-Query-Cache, X-Query-Shards, X-RateLimit-Remaining.

14) Quote, limiti di rate e backpressure

Il valore predefinito è 10 rps per cliente, 50 puntate per risposta, 3 ore, «step ≥ 10c».
Burst-token - Per i dashboard sul grande schermo, finestre coerenti.
Backpressure: il server può restituire «Retry-After» consigliando di aumentare «step »/attivare« downsample ».

15) SDK e migliori pratiche

SDK: Typescript/Go/Python. La cache predefinita è aggressiva, backoff esponenziale, If-None-Match.

• raggruppare le richieste attraverso «/bulk-query »;
• Utilizzare «group _ by» in modo economico;
• per le recensioni storiche: 'downsample = 1h';
• Aggiungete timeout 2 c e «cancellation» - ticken.

15. 1 Mini esempio (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) Osservabilità API metriche

SLI самого API: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
Utilizzo KPI: rps, quantità media di risposta, top metriche in base al costo.
Alert: burn-rate per errore, picco «429», caduta cache-hit <target.
Loghi: strutturati, senza PII; tenant, metric _ id, query _ cost _ class.

17) Criteri FinOps

Classi di query: A (realtime dashboard), B (operativo), C (analista). Quote diverse/TTL.
Costo: $/GB letture, $/richiesta, $/conte. Rapporto mensile su metriche e etichette pesanti.
Ottimizzazioni: merge server, preagregati per i popolari SLO-View, suggerimenti auto al cliente (suggested'step/downsample ').

18) Integrazioni

Stato pagina - Legge le pagine SLO finite.
Alerting, le regole si basano su «/slo »e« instant ».
Incidente-bot: snippet veloci di grafici/tagli attraverso brevi preset.
Workflow/Release-gates - Unità di rilascio con SLO rosso.

19) Road map di implementazione (6-10 settimane)

Ned. 1-2: catalogo di metriche, etichette whiteliste, schemi «/catalog », prototipo «/query» con cache e downsample.
Ned. 3-4: '/bulk-query ', '/slo', exemplars, RBAC/ABAC, quote/rate-limite.
Ned. 5-6: geo-sharding, CDN per il pubblico, titoli FinOps, dashboard SLI API.
Ned. 7-8: SDK (TS/Go/Py), raccomandazioni/linter di query, test canarini.
Ned. 9-10: esercitazioni di caos (guasto di chard/cache), ottimizzazione dei costi, politica dei deprecati.

20) Manufatti

Metric Catalog: id, unità, descrizioni, «agg» disponibili, etichette valide.
Ruoli, aree, limiti, SoD.
Query Style Guide - Esempi di richieste corrette/errate.
La SLO MAP è un obiettivo pubblico.
Cost Report: le richieste/etichette più costose, il piano di ottimizzazione.

21) KPI/KRI API metriche

p95/99 latency, error rate, partial responses.
Cache hit ratio e risparmio CPU/IO.
Dimensione media della risposta e $/richiesta.
Percentuale di dashboard passati a/bulk-query.
Incidenti dovuti a richieste di alta radicalità.

22) Antipattern

Il «gruppo _ by» libero da dozzine di etichette ha fatto esplodere la cardinalità.
Percentili, piegati su un cliente di distorsione.
Le richieste per 30-90 giorni senza downsample sono costose e lente.
Miscelare tenenti/regioni in una sola risposta senza autorizzazione.
Pannelli pubblici senza cache/CDN.
Modifica della semantica delle metriche senza «vX» e grace.

Totale

L'API metrica delle operazioni è uno strato di lettura stabile, sicuro ed economico sopra la telemetria: schemi standardizzati e perfils, cache e downsampling, etichette e accessibilità rigorose, SLO-View ed exemplars per RCA, SLA trasparenti e costo. Questo strato consente di costruire dashboard affidabili, alerting, comunicazione status e gate di rilascio senza rischi per privacy, budget e produttività.