Como Monitorar API Routes do Next.js Sem Agentes Externos

Sao 2 da manha. Seu endpoint /api/checkout esta retornando erros 500 ha 47 minutos. Seu monitor de uptime externo? Mostra verde. O health check responde 200 OK a cada 60 segundos, como se nada estivesse errado.

Enquanto isso, 340 requests reais de checkout falharam. Voce descobre na manha seguinte por um backlog de webhooks do Stripe e tres emails de clientes irritados.

Este e o problema do monitoramento externo para APIs do Next.js. Ele verifica a porta da frente. Nao sabe o que acontece dentro.

Por que o monitoramento externo nao e suficiente para Next.js

Ferramentas como Pingdom, UptimeRobot e ate os synthetic checks do Datadog funcionam da mesma forma: enviam um request HTTP para uma URL a cada N segundos e verificam se a resposta e 200. So isso.

Para uma aplicacao Next.js, esse modelo tem pontos cegos fundamentais:

• So testa um endpoint por vez. Se voce tem 15 API routes, precisa de 15 monitores separados.
• Nao detecta falhas intermitentes. Se seu /api/payments falha em 3 de cada 100 requests por uma race condition, um ping a cada 60 segundos nunca vai capturar isso.
• Nao mede latencia real. O round-trip da Virginia inclui latencia de rede, cache de CDN e routing de edge. Nada disso reflete o que seus usuarios experimentam.
• Nao funciona atras de firewalls. Se sua API e interna, pings externos literalmente nao alcancam ela.
• Cold starts quebram as medicoes. Um health check que atinge uma funcao warm mede 50ms. Um usuario real em cold start recebe 1800ms.

O Hook de Instrumentacao do Next.js

Desde o Next.js 13.2, existe uma forma nativa de executar codigo quando o servidor inicia: o hook de instrumentacao. Voce cria um arquivo instrumentation.ts na raiz do projeto, e o Next.js chama sua funcao register() uma vez durante a inicializacao.

// instrumentation.ts
export async function register() {
  // Executa uma vez quando o servidor inicia.
  // Ideal para inicializar monitoramento, tracing ou logging.
  console.log('Servidor inicializado - monitoramento ativo')
}

Monitor basico de requests do zero

Para entender como funciona o monitoramento interno, aqui esta uma implementacao minima usando middleware do Next.js:

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const start = Date.now()
  const response = NextResponse.next()
  const duration = Date.now() - start
  const path = request.nextUrl.pathname

  if (path.startsWith('/api/')) {
console.log(JSON.stringify({
  path,
  method: request.method,
  duration,
  timestamp: new Date().toISOString(),
}))
  }

  return response
}

export const config = {
  matcher: '/api/:path*',
}

Isso te da logs estruturados de cada API request. Mas e so logging, sem alertas, sem agregacao, sem dashboards. Para producao voce precisaria de um banco de dados de series temporais, calcular percentis, construir alertas e manter toda essa infraestrutura.

Monitoramento externo vs interno

O atalho prático: OpenTelemetry em 5 linhas

Você não precisa fazer patch nos internals do Node.js. O Next.js tem suporte nativo a OpenTelemetry: quando você registra um provider de OTel no hook de instrumentação, o Next.js emite spans dos requests e route handlers dentro do seu servidor.

npm install @vercel/otel

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

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

Depois você exporta os traces para qualquer backend compatível com OTLP, self-hosted ou SaaS:

• Todas as rotas cobertas: Os requests para suas API routes são rastreados conforme acontecem.
• Métricas reais: Response time, status codes e erros de cada endpoint, medidos em requests reais.
• Alertas: Configure no seu backend (Slack, email, etc.) sobre taxa de erros ou latência por rota.
• Sem lock-in: OTel é um padrão aberto, dá para trocar de backend sem reinstrumentar.

Comece agora

1. Execute npm install @vercel/otel
2. Adicione as 5 linhas ao instrumentation.ts
3. Aponte o exporter OTLP para o backend que você escolheu
4. Faça deploy
5. Crie alertas de P95 e taxa de erros por rota, e adicione um check de uptime externo para quedas totais

Seu /api/checkout as 2 da manha nunca mais vai falhar em silencio.