Monitoramento de REST API: O Que Rastrear e Quais Ferramentas Usar

Sua REST API esta "no ar." Parabens. Isso nao diz quase nada.

Uptime significa que o servidor responde. Nao diz que /api/checkout demora 4 segundos em vez de 400 milissegundos. Nao diz que 3% dos requests para /api/users retornam 500.

Metrica 1: Uptime: Mas medido corretamente

O que a maioria faz: Um servico externo pinga /api/health a cada 60 segundos. Se retorna 200, a API esta "no ar."

O que voce deveria fazer: Calcular uptime a partir de dados de requests reais. Se voce serviu 1,000,000 de requests e 2,000 retornaram 5xx, seu uptime efetivo e 99.8%.

Metrica 2: Percentis de latencia: P50, P95, P99

O tempo de resposta medio e mentira. Se 99 requests demoram 50ms e 1 demora 10 segundos, a media e 149ms. Esse numero esconde que 1% dos seus usuarios tem uma experiencia terrivel.

• P50 (mediana)A experiencia tipica.
• P95Os 5% mais lentos. Captura queries lentas, cold starts e problemas n+1.
• P99O 1% pior. Um usuario que faz 100 chamadas tem 63% de probabilidade de experimentar o P99 pelo menos uma vez.

Alvos: P50 abaixo de 100ms, P95 abaixo de 500ms, P99 abaixo de 2 segundos.

Metrica 3: Taxa de erro por endpoint

Uma taxa de erro global de 0.5% parece ok. Mas e se todos os erros vem de um unico endpoint?

// Vista global: 0.5% taxa de erro, parece ok
// Vista por endpoint:
// GET  /api/users     → 0.01% erros 
// POST /api/checkout  → 12.4% erros   ← Aqui estao todos os erros

Metrica 4: Throughput: Requests por minuto

Throughput combinado com latencia e erros se torna diagnostico:

• Throughput sobe + latencia sobe = Aproximando-se do limite de capacidade
• Throughput sobe + erros sobem = Ja passou do limite
• Throughput desce + latencia sobe = Uma dependencia esta lenta

Metrica 5: Deteccao de endpoints lentos

Limites estaticos ("alertar se resposta > 2 segundos") nao funcionam quando voce tem 30 endpoints com faixas normais diferentes. A deteccao de endpoints lentos identifica automaticamente quais rotas estao degradando relativo a sua propria baseline.

Comparacao de ferramentas

Setup no Next.js com OpenTelemetry

Uma forma neutra em relacao a vendor e registrar o OpenTelemetry no hook instrumentation.ts (com @vercel/otel e suas dependencias) e apontar o exporter para o seu backend com OTEL_EXPORTER_OTLP_ENDPOINT:

// instrumentation.ts
import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel({ serviceName: 'my-api' })
}

Com os dados chegando, monte no seu backend dashboards e alertas de P50/P95/P99, taxas de erro, throughput e endpoints lentos em relacao a sua baseline. Some um check externo de uptime para quedas totais.

O que fazer depois do setup

1. Semana 1: Observar. Nao definir limites ainda. Deixar a ferramenta estabelecer baselines.
2. Semana 2: Definir limites de P95 por endpoint (2x a baseline e um bom ponto de inicio).
3. Semana 3: Definir limites de taxa de erro. 0.5% para endpoints criticos, 2% para o resto.
4. Continuo: Revisar semanalmente. Procurar tendencias lentas.