API métricas de operações

1) Atribuição e área de responsabilidade

• SLI/SLO consistentes (login, depósito, taxa, conclusão);
• KRI (PSP/KYC/filas/replicação);
• métricas de negócios (sucesso de autorizações GEO/PSP/bancos, proporção de apostas de sucesso, p95/p99 longas de caminhos-chave);
• leituras seguras, baratas e previsíveis para dashboards, alerting, status de página, relatórios.

2) Princípios arquitetônicos

Read-heavy, write-few: API só lê agregados de TSDB/cachê.
SLO-first: as respostas são previsíveis no tempo; erros e degradação - transparentes.
Costa-aware: downsampling, quotas, fios de canário em SDK.
Privaciy-by-design: Nada de PII em metadados/editoras; tocens, geo-gate, SoD.
Multi-tenant: isolamento por marca/região/ambiente.

3) Modelo de dados (superficial)

Série de métricas = 'metric _ id' + 'labels\' +' timestamp '+' value '(+ opcional' excemplar '\trace _ id =... a.').

3. 1 Categorias

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 Editoras (estritamente limitadas)

`region`, `tenant`, `environment`, `service`, `psp`, `bank_group`, `geo`, `device`, `version`, `component`.
Proibido: «userId», «sessionId», números crus de cartões/documentos.

4) Versionização e compatibilidade

Caminho básico: '/v1/metrics/... '; alterações incompatíveis apenas no novo «vX».
Adição de editoras/séries - backward-compatível.
A mudança de semântica é através do campo 'schema _ version' na resposta e do período grace.
O catálogo de esquemas é publicado como '/v1/schemas '.

5) Endpoints (REST, similar em 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`.
• Resposta: Matriz de filas de '

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

Corpo: até 50 pedidos com um único batch. Economiza consultas para dashboards complexos.

3. `GET /v1/metrics/instant`

Valores atuais no momento 'ts' (ou 'agora') com os filtros especificados.

4. `GET /v1/metrics/catalog`

Lista de métricas, descrições, editoras, agregações válidas, referências SLO disponíveis.

5. `GET /v1/metrics/health`

O estado da API em si é latency p95, a resistência ao cachê, a taxa de sucesso em dinheiro.

6. `GET /v1/metrics/slo`

Visto SLO pronto: consumo de orçamento de erros (fast/slow), estados de metas.

6) Exemplos de solicitação

6. 1 Sucesso de Autorizações PSP em TR, grid de 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» por região, com exemplars (exemplos de trace):

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

6. 3 Status instantâneo de depósito SLO por EU:

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

6. 4 Batch de 3 consultas (POST/bulk-query) - para um grafo com camadas.

7) Agregações e percalços

Os percêntios p50/p95/p99 são computados no nível TSDB/agregador; em 'downsample' - com composição correta (t-digest/HDR).
'grupo _ by' só é permitido através de editoras whitelisted para não explodir a radicalidade.
'step' valida: mínimo de 10s para realtime, 1m para dashboards públicos.

8) Cash, downsampling e frescor

Em-memory em vários níveis (até 30-60 s), distribuído (até 5 min), CDN para visualização SLO pública.
Downsampling: máquina em janelas maiores ('> 24h') → pontos 5m/1h.
Freshness-заголовки: `X-Data-Freshness: 12s`, `X-Downsample: 1m`, `X-Partial: true|false`.

9) Multi-tenente e isolamento

Cada pedido deve conter «tenant» (em token/editoras).
ABAC/RBAC: O papel/política restringe o acesso por 'tenant, region, ambientonment, metric _ id'.
Show/charge-back: cabeçalhos 'X-Query-Cost-Estimate' e contadores usage.

10) Autenticação e segurança

OAuth2 mTLS/tokens de serviço com limitação de scope.
SoD: Acesso a métricas com possíveis riscos regulatórios (finanças, RG) - papéis individuais.
Rate limits: pela chave do cliente e por 'metric _ id'.
Saúde PII: o servidor valida a ausência de filtros/editoras proibidos.

11) Geo residente e complacência

Os dados são lidos a partir da política de residência regional (EU/LATAM/APAC).
Solicitações cruzadas - somente para unidades sem PII e com 'compliance _ scope'.

12) Instâncias/Exemplars e correlação

Quando 'exemplars = true', os pontos de percalço remetem a um par de 'trace _ id' representativo (sem PII) para um RCA rápido.
A correlação 'correlation _ id' está disponível nos metadados de resposta.

13) SLA API e erros

Resposta SLA: p95 ≤ 300 ms (dinheiro), ≤ 1. 5 c (caminho frio), disponibilidade ≥ 99. 9%.

• '400' - Pedido de nevalida (demasiado 'grupo _ by', mau 'step'),
• '403' - direitos insuficientes/tenante,
• '409' - conflito de esquema,
• '429' - quota/limite de rate,
• '502/504' - degradação do estorvo (em cabeçalhos - recomendações de downsample/step),
• '206' - resposta parcial (parte dos chardes não estão disponíveis).
• Os cabeçalhos do diagnóstico são: 'X-Query-Place', 'X-Query-Shards', 'X-RateLimit-Remaining'.

14) Quotas, limites de rate e backpressure

Padrão: 10 rps por cliente, 50 séries por resposta, janela 3 horas, 'step ≥ 10c'.
Burst-tokens: para dashboards para tela grande, janelas alinhadas.
Backpressure: o servidor pode devolver 'Retry-After' aconselhando-o a aumentar 'step '/ativar' downsample '.

15) SDK e melhores práticas

SDK: Typescript/Go/Python. Por padrão, dinheiro agressivo, backoff exponencial, 'If-None-Match'.

• agrupe as pesquisas através de '/bulk-query ';
• use 'group _ by' economicamente;
• para revisões históricas - 'downsample = 1h';
• Adicione times ≤ 2 c e 'cancellation' -

15. 1 Mini-exemplo (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) Observabilidade da API métricas

SLI самого API: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
Uso KPI: rps, média de resposta, alta métrica em valor.
Alerts: burn-rate por erro, sobe '429', queda cachê-hit <alvo.
Logi: estruturado, sem PII; 'tenant', 'metric _ id', 'query _ cost _ class'.

17) Políticas FinOps

Classes de consulta: A (realtime dashboard), B (operacional), C (analista). Diferentes quotas/TTL.
Custo: $/GB leitura, $/consulta, $/conde. Relatório mensal de métricas e editoras pesadas.
Otimizações: merge servidor, pré-regatas para os populares SLO-View, dicas automáticas ao cliente (suggested 'step/downsample').

18) Integração

Página de status: Leia SLO-View pronto.
Alerting: as regras são baseadas em '/slo 'e' instantâneo '.
Incidente-bot, comprimidos rápidos de gráficos/cortes através de presídios curtos.
Workflow/Release-gates: unidade de lançamento com SLO vermelho.

19) Mapa de trânsito de implementação (6-10 semanas)

Ned. 1-2: catálogo de métricas, editoras whitelistas, esquemas '/catalog ', protótipo '/query' com dinheiro e downsample.
Ned. 3-4: '/bulk-query ', '/slo', exemplars, RBAC/ABAC, quotas/limites de rate.
Ned. 5-6: geo-charding, CDN para viés público, títulos FinOps, dashboard SLI API.
Ned. 7-8: SDK (TS/Go/Py), recomendações/linter de solicitação, testes canários.
Ned. 9-10: Ensinamentos de caos (falha de chard/cachê), otimização de custo, política de depredação.

20) Artefactos

Metric Catalog: id, unidades, descrições, 'agg' disponíveis, editoras válidas.
Access Policy: papéis, áreas, limites, SoD.
Query Style Guide: exemplos de solicitações corretas/incorretas.
SLO Map: alinhamento do SLI ↔ objetivos públicos.
Caro Report: topo de consultas/marcas de custo, plano de otimização.

21) KPI/KRI API métricas

p95/99 latency, error rate, partial responses.
Cachê hit ratio e poupança CPU/IO.
Tamanho médio da resposta e $/consulta.
Proporção de dashboards que passaram para '/bulk-query '.
Incidentes por causa de pedidos de alta radicalidade.

22) Antipattern

Livre 'group _ by' por dezenas de marcas → explosão de radicalidade.
Os percentis «dobrados» no cliente → distorções.
Pedidos de 30 a 90 dias sem downsample são → caros e lentos.
Mistura de tenentes/regiões em uma única resposta sem autorização.
Painéis públicos sem cachê/CDN.
Altera a semântica das métricas sem 'vX' e no período grace.

Resultado

A API de operações é uma camada de leitura estável, segura e econômica sobre a telemetria, como circuitos e percalços normalizados, dinheiro e downsampling, editoras e acessos rigorosos, SLO-view e exemplars para RCA, SLA transparente e custo. Esta camada permite a construção de dashboards confiáveis, alerting, comunicações de status e lançamentos de gate sem risco de privacidade, orçamento e produtividade.