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

Como o Nurbak Watch resolve isso em 5 linhas

Nurbak Watch e um SDK de monitoramento de APIs construido especificamente para Next.js. Usa o hook de instrumentacao para rodar dentro do seu servidor.

npm install @nurbak/watch

// instrumentation.ts
import { initWatch } from '@nurbak/watch'

export function register() {
  initWatch({
apiKey: process.env.NURBAK_WATCH_KEY,
  })
}

5 linhas. Depois do deploy:

• Auto-discovery: Cada API route e detectado automaticamente.
• Metricas em tempo real: Response time, status codes e error rates de cada endpoint.
• Alertas instantaneos: Slack, email ou WhatsApp em menos de 10 segundos quando um endpoint falha.
• Zero infraestrutura: As metricas sao enviadas para a nuvem do Nurbak.

Comece agora

Nurbak Watch esta em beta e e gratis durante o lancamento. Sem cartao de credito, sem limites de teste.

1. Va para nurbak.com e crie uma conta
2. Execute npm install @nurbak/watch
3. Adicione as 5 linhas ao instrumentation.ts
4. Faca deploy
5. Veja cada API route aparecer no seu dashboard em 60 segundos

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