Seu app Next.js está em produção. Usuários estão usando seus API routes. Mas como você sabe se /api/users responde em 200ms ou 2000ms? Como sabe se seu webhook de pagamentos está retornando erros 500 às 3 da manhã?

A maioria dos developers faz deploy e torce pelo melhor. Neste guia, você vai aprender a configurar monitoramento real para seus API routes do Next.js (com health checks automáticos, tracking de latência e alertas instantâneos) sem adicionar um APM pesado.

Por que monitorar API Routes do Next.js?

API routes do Next.js são funções serverless (no Vercel) ou handlers tipo Express (no Node). Em ambos os casos, podem falhar silenciosamente:

  • Cold starts podem disparar a latência de 50ms para 2000ms+
  • Conexões com banco de dados podem dar timeout sem erros visíveis
  • APIs de terceiros (Stripe, Auth0, etc.) podem degradar e causar falhas em cascata
  • Certificados SSL podem expirar e quebrar todo o tráfego HTTPS
  • Mudanças de DNS podem propagar incorretamente entre regiões

Sem monitoramento, você só descobre quando os usuários reclamam, ou quando a receita cai.

Passo 1: Adicionar um endpoint de health

Dê ao seu monitoramento algo que faça sentido checar. Uma rota de health que toca suas dependências reais (banco de dados, cache) detecta muito mais que um check na sua home:

// app/api/health/route.ts
import { db } from '@/lib/db'

export async function GET() {
  try {
    await db.query('SELECT 1')
    return Response.json({ status: 'ok' })
  } catch {
    return Response.json({ status: 'error' }, { status: 503 })
  }
}

Retorne um status diferente de 200 quando uma dependência falhar, assim qualquer checker externo detecta sem precisar ler o body.

Passo 2: Instrumentar suas rotas

Crie instrumentation.ts na raiz do projeto e registre o OpenTelemetry. Cada rota gera traces com duração e status, que você pode enviar para o backend de observabilidade que já usa:

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

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

Passo 3: Agendar checks externos e alertas

Métricas internas não avisam quando o app inteiro está fora do ar. Para isso você precisa de um check rodando fora do seu deploy. Qualquer ferramenta de uptime faz isso; a versão em código puro é assim:

// check.ts, run every minute from a scheduler outside your app
const url = 'https://your-app.com/api/health'
const start = Date.now()
let status = 0
try {
  const res = await fetch(url, { signal: AbortSignal.timeout(10_000) })
  status = res.status
} catch {}
const ms = Date.now() - start

if (status !== 200 || ms > 2000) {
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text: `${url} returned ${status || 'no response'} in ${ms}ms` }),
  })
}

Alerte para API fora do ar, alta latência, taxa de erros ou expiração SSL, e envie os alertas para um canal que alguém realmente olhe (Slack, email ou SMS para o que for crítico).

Passo 4: Deploy e verificar

Faça deploy normalmente e depois quebre algo de propósito num preview (por exemplo, uma URL de banco de dados errada) para confirmar que o alerta chega. Um alerta que você nunca testou é um alerta em que não dá para confiar.

Monitoramento Multi-Região

Rode os checks de várias regiões (por exemplo Estados Unidos, São Paulo, Europa e Tóquio). Isso permite detectar quedas regionais, como quando seu deploy no Vercel funciona nos US mas faz timeout da Europa.

Dá para fazer de graça?

Sim. A rota de health, o OpenTelemetry e um check agendado com alertas por webhook do Slack não custam nada além de alguns minutos de setup. Muitos serviços de uptime também têm planos gratuitos com intervalos mais lentos (geralmente a cada 5 minutos). O que você paga nos planos pagos são intervalos menores, mais regiões e mais canais de alerta.

Resumo

Monitorar seus API routes do Next.js se resume a três peças: um endpoint de health que toque suas dependências reais, instrumentação para latência P95 e taxa de erros por rota, e checks externos de várias regiões que avisem por Slack, email ou SMS. Não espere os usuários reportarem problemas, saiba primeiro.