Uso e métricas

O produto oferece três visões diferentes, e é importante não confundi-las:

Visão	O que responde	Retenção
Uso agregado	quantas requisições, erros, bytes, latência média e máxima	35 dias em minuto; 13 meses em hora
Métricas de runtime	requisições, taxa de erro e p50/p95/p99 no período	a do sistema de métricas da plataforma (90 dias)
Logs de acesso	linha a linha do que aconteceu	3 dias

Uso agregado

GET /v1/apis/{apiId}/usage?from=…&to=…&granularity=minute|hour|day

• janela padrão: as últimas 24 h; a máxima depende da granularidade — minute 3 dias, hour 90 dias, day 400 dias. Acima disso: 400 validation_error com reason = window_too_large;
• from precisa ser anterior a to (400, reason = invalid_window); timestamp fora do ISO-8601 é 400 (reason = invalid_timestamp);
• devolve series (pontos por balde) e totals;
• os baldes são em UTC (hour e day alinhados à hora e ao dia UTC); some sempre em UTC e apresente no fuso do usuário só na tela;
• a fonte é o minuto (35 dias) e, para o trecho mais antigo da janela, a hora consolidada (13 meses) — o resultado é o mesmo que somar os minutos;
• campos: requests, status2xx, status4xx, status5xx, bytes_in, bytes_out, latency_avg_ms, latency_max_ms.

GET /v1/usage?from=…&to=…&limit=… devolve os totais da organização, as APIs mais chamadas e os consumidores que mais consomem (até 50 itens; limit acima de 50 é reduzido a 50). Janela máxima: 400 dias.

Consolidação: o minuto vira hora em segundo plano (o rollup é recalculado dos próprios minutos) e o trecho da janela anterior à retenção dos minutos vem da hora consolidada. Não há "buraco" na série: o rollup roda a cada 10 minutos e refaz também horas que receberam evento atrasado.

Métricas de runtime

GET /v1/apis/{apiId}/metrics?range=5m|15m|30m|1h|3h|6h|12h|24h|7d (padrão 1h)

• sempre filtrado pela API;
• devolve requests, errors, error_rate e latency.p50_ms, p95_ms e p99_ms (do histograma de latência do data plane);
• se a fonte não estiver configurada, a resposta é 503.

Os rótulos das métricas carregam só ids: code, route, service (a API) e matched_host. node, matched_uri e consumer estão desligados de propósito, por cardinalidade — nenhuma URL ou nome de cliente vira rótulo.

Logs de acesso

São a linha a linha do que aconteceu, com retenção de 3 dias. O detalhe está em Logs de acesso.

Saúde da API

O status da API traz, além do estado de publicação, a parte observada:

Bloco	O que diz
gateway	estado do gateway para a API: active, pending, degraded, disabled ou not_published, com motivo, revisão publicada, quando a publicação foi confirmada e o estado de cada réplica
backends	por backend da revisão publicada: healthy, unhealthy ou unknown, com motivo, saúde por alvo (host:porta) e por réplica
certificates	por hostname (padrão e domínios próprios): valid, expiring (menos de 14 dias), expired ou pending
last_check	última leitura do monitor de saúde

Motivos de unknown num backend: not_configured (não há verificação de saúde), warming_up, no_observation, stale (observação mais velha que o limite) e partial_observation.

O que mais confunde: o verificador só ganha os alvos depois da primeira requisição que passa pelo upstream em cada réplica. API publicada e sem tráfego fica unknown (no_observation) mesmo com o backend perfeito — não é falha, é ausência de observação. Faça uma chamada e o estado aparece no ciclo seguinte do monitor.

A primeira leitura pode demorar até um intervalo do monitor (15 s) mais o aquecimento.

Como usar cada uma

Pergunta	Use
"Quantas chamadas esta API recebeu no mês?"	uso agregado, granularidade day
"Qual o p95 agora?"	métricas de runtime
"O que aconteceu naquela requisição das 14h32?"	logs — se estiver dentro dos 3 dias
"Quem consome mais?"	uso da organização (/v1/usage)
"O erro foi meu ou do meu backend?"	logs (campo status e upstream_time), métricas de erro e a saúde do backend no status
"O backend está no ar e saudável?"	status da API, bloco backends

Limitações a comunicar

1. Logs: 3 dias. Para histórico, o caminho é o uso agregado, não os logs.
2. Métricas são aproximadas — servem para operação e gráficos, não para faturamento.
3. A medição pode perder eventos de lote que esgotou as tentativas ou de máquina que caiu com lote em memória. Consequência: não trate estes números como base de faturamento exato.
4. O consumo do API Gateway é medido separadamente do consumo de outros produtos.

Próximos passos

• Logs de acesso: campos, janela e retenção.
• Visão geral da API: todos os blocos do status.
• Políticas de tráfego e limites: o que gera 429.