API de métricas de operaciones

1) Nombramiento y zona de responsabilidad

• SLI/SLO consistentes (inicio de sesión, depósito, tasa, retiro);
• KRI (indicadores de riesgo tempranos: PSP/KYC/colas/replicaciones);
• métricas empresariales (éxito de las autorizaciones GEO/PSP/bancos, porcentaje de tasas exitosas, duración p95/p99 de las rutas clave);
• lecturas seguras, baratas y predecibles para dashboards, alertas, páginas de estado, informes.

2) Principios arquitectónicos

Read-heavy, write-few: la API sólo lee agregaciones de TSDB/caché.
SLO-first: las respuestas son predecibles en el tiempo; errores y degradación - señalización transparente.
Costo-aware: downsampling, cupos, fiches canarios en SDK.
Privacidad por diseño: sin PII en metadatos/etiquetas; tokens, geo-gate, SoD.
Multi-tenant: aislamiento por marca/región/entorno.

3) Modelo de datos (superficial)

Serie métrica = 'metric _ id' + 'labels {}' + 'timestamp' + 'value' (+ opcional 'exemplar {trace _ id =...}').

3. 1 Categorías

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 Etiquetas (estrictamente limitadas)

`region`, `tenant`, `environment`, `service`, `psp`, `bank_group`, `geo`, `device`, `version`, `component`.
Prohibido: 'userId', 'sessionId', números crudos de tarjetas/documentos.

4) Versificación e interoperabilidad

Ruta básica: '/v1/metrics/... '; cambios incompatibles - sólo en el nuevo 'vX'.
Agregar etiquetas/series - backward-compatible.
Cambio de semántica - a través del campo 'schema _ version' en respuesta y período de gracia.
El catálogo de esquemas se publica como '/v1/schemas '.

5) Endpoints (NAT, similar en 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`.
• Respuesta: matriz de series '{metric, labels {}, points: [[ts, value]], exemplars?}'.

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

Cuerpo: hasta 50 consultas con un trampolín. Ahorra solicitudes para dashboards complejos.

3. `GET /v1/metrics/instant`

Valores actuales en el momento 'ts' (o' ahora ') con los filtros especificados.

4. `GET /v1/metrics/catalog`

Lista de métricas disponibles, descripciones, etiquetas, agregaciones válidas, enlaces SLO.

5. `GET /v1/metrics/health`

El estado de la API en sí: latency p95, la tolerancia a errores de la caché, la fracción de los hits de caché.

6. `GET /v1/metrics/slo`

Listo para SLO-view: consumo de presupuesto de errores (fast/slow), estados de objetivos.

6) Ejemplos de consultas

6. 1 Éxito de las autorizaciones PSP en 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» por región, con exemplars (ejemplos de tres):

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

6. 3 Estado instantáneo de los depósitos SLO de la UE:

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

6. 4 Batch de 3 consultas (POST/bulk-query) - para un gráfico con capas.

7) Agregaciones y percentili

Los percentili p50/p95/p99 se calculan en el nivel TSDB/agregador; con 'downsample' - con la composición correcta (t-digest/HDR).
'group _ by' solo está permitido por etiquetas whitelisted para no reventar la cardinalidad.
'step' valida: mínimo de 10s para realtime, 1m para dashboards públicos.

8) Caché, descarga y frescura

Caché en niveles: en memoria (hasta 30-60 s), distribuido (hasta 5 min), CDN para SLO-view público.
Downsampling: automático con ventanas grandes ('> 24h') → 5m/1h puntos.
Freshness-заголовки: `X-Data-Freshness: 12s`, `X-Downsample: 1m`, `X-Partial: true|false`.

9) Multi-tenant y aislamiento

Cada solicitud debe contener 'tenant' (en token/etiquetas).
ABAC/RBAC: el rol/política restringe el acceso por 'tenant, region, environment, metric_id'.
Show/charge-back: encabezados 'X-Query-Cost- Estimate' y contadores usage.

10) Autenticación y seguridad

OAuth2 mTLS/tokens de servicio con límite de scope.
SoD: acceso a métricas con posibles riesgos regulatorios (finanzas, RG) - roles separados.
Rate limits: por clave de cliente y por 'metric _ id'.
Sanidad PII: el servidor valida la ausencia de filtros/etiquetas prohibidas.

11) Geo-residencia y cumplimiento

Los datos se leen de los storage regionales (EU/LATAM/APAC) sobre políticas de residencia.
Consultas regionales cruzadas: sólo para agregados sin PII y si hay 'compliance _ scope'.

12) Instancias/Exemplares y correlación

Con 'exemplars = true' en la respuesta, en los puntos de percentil se devuelven las referencias a un par de 'trace _ id' representativos (sin PII) para un RCA rápido.
Correlación: 'correlation _ id' está disponible en los metadatos de respuesta.

13) SLA API y errores

Respuesta SLA: p95 ≤ 300 ms (caché), ≤ 1. 5 s (ruta fría), accesibilidad ≥ 99. 9%.

• '400' es una consulta invisible (demasiado 'group _ by', mal 'step'),
• '403' - derechos/tenantes insuficientes,
• '409' - conflicto de esquemas,
• '429' - cuota/límite de velocidad,
• '502/504' - degradación de storage (en los encabezados - recomendaciones para downsample/step),
• '206' es una respuesta parcial (parte de los chardos no están disponibles).
• Los titulares de diagnóstico son: 'X-Query-Plan', 'X-Query-Cache', 'X-Query-Shards', 'X-RateLimit-Remaining'.

14) Cuotas, límites de velocidad y retroceso

Por defecto: 10 rps por cliente, 50 series por respuesta, ventana 3 horas, 'step ≥ 10c'.
Burst-tokens: para dashboards en la pantalla grande, ventanas coherentes.
Backpressure: el servidor puede devolver 'Retry-After' aconsejando aumentar 'step '/habilitar' downsample '.

15) SDK y mejores prácticas

SDK: Typescript/Go/Python. Por defecto: caché agresivo, backoff exponencial, 'If-None-Match'.

• agrupar las solicitudes a través de '/bulk-query ';
• utilice 'group _ by' de forma económica;
• para revisiones históricas - 'downsample = 1h';
• agregue tiempos de espera ≤ 2 s y «cancellation» -tokens.

15. 1 Mini ejemplo (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) Observabilidad de las métricas API

SLI самого API: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
KPI de uso: rps, volumen de respuesta promedio, métricas superiores por costo.
Alertas: burn-rate por error, ráfaga '429', caída cache-hit <objetivo.
Registros: estructurados, sin PII; 'tenant', 'metric _ id', 'query _ cost _ class'.

17) Políticas FinOps

Clases de consulta: A (realtime dashboards), B (operative), C (analytics). Diferentes cuotas/TTL.
Costo: $/GB lectura, $/consulta, $/grafo. Informe mensual sobre métricas y etiquetas «pesadas».
Optimizaciones: servidor merge, preagrupaciones para SLO-view populares, consejos automáticos al cliente (suggested 'step/downsample').

18) Integración

Status page: lee SLO-view listo.
Alerting: las reglas se basan en '/slo 'y' instant '.
Incidente-bot: snippets rápidos de gráficos/cortes a través de presets cortos.
Workflow/Release-gates: bloque de lanzamientos en SLOs rojos.

19) Hoja de ruta para la implementación (6-10 semanas)

Ned. 1-2: catálogo de métricas, etiquetas whitelists, circuitos '/catalog ', prototipo '/query' con caché y downsample.
Ned. 3-4: '/bulk-query ', '/slo', exemplares, RBAC/ABAC, cuotas/límites de velocidad.
Ned. 5-6: geo-sharding, CDN para el público view, FinOps-heads, dashboard SLI API.
Ned. 7-8: SDK (TS/Go/Py), recomendaciones/linter de consultas, pruebas canarias.
Ned. 9-10: simulacros de caos (fracaso de Shard/Cache), optimización de costos, política de deprecates.

20) Artefactos

Catálogo métrico: id, unidades, descripciones, 'agg' disponibles, etiquetas válidas.
Política de acceso: roles, áreas, límites, SoD.
Query Style Guide: ejemplos de consultas correctas/incorrectas.
Mapa de SLO: cumplimiento de SLI ↔ objetivos públicos.
Informe Costo: Top de consultas/etiquetas costosas, plan de optimización.

21) Métricas de API KPI/KRI

p95/99 latency, error rate, partial responses.
Cache hit ratio y ahorro de CPU/IO.
Tamaño de respuesta promedio y $/solicitud.
Proporción de dashboards que han cambiado a '/bulk-query '.
Incidentes por peticiones de alta cardinalidad.

22) Antipatternas

Libre 'group _ by' por decenas de etiquetas → una explosión de cardinalidad.
Percentili «apilados» en el cliente → distorsión.
Las solicitudes para 30-90 días sin downsample → costosas y lentas.
Mezclar tenantes/regiones en una respuesta sin autorización.
Paneles públicos sin caché/CDN.
Cambiar la semántica de métricas sin 'vX' y período grace.

Resultado

La API de métricas de operaciones es una capa de lectura estable, segura y económica sobre telemetría: circuitos y percentils estandarizados, caché y downsampling, etiquetas y accesos estrictos, SLO-view y exemplars para RCA, SLAs transparentes y costo. Esta capa le permite construir dashboards confiables, alertas, comunicaciones de estado y lanzamientos sin riesgos para la privacidad, el presupuesto y la productividad.