Next.js shippeo instrumentation.ts en la versión 13.4 y lo estabilizó en la 15. Es la forma oficial y soportada de enganchar código de monitoreo a tu servidor Next.js. Si shippéas Next.js a producción y no lo usás, o te falta telemetría o estás pagando un setup más complicado del que necesitás.

Qué es instrumentation.ts

instrumentation.ts es un archivo especial que vive en la raíz de tu proyecto Next.js. Next.js lo busca al boot del servidor y llama a su función register exportada una sola vez, antes de manejar cualquier request.

// instrumentation.ts
export async function register() {
  // Esto corre una vez, en el server, al boot
}

Ese es todo el contrato. Lo que pongas en register() corre en el runtime del server antes de que el tráfico llegue a tus rutas. Es el lugar correcto para inicializar SDKs de monitoreo, registrar instrumentaciones de OpenTelemetry, configurar loggers, y validar config de entorno antes de servir tráfico.

Cómo habilitarlo

En Next.js 15 está habilitado por defecto. Solo creá el archivo en la raíz del proyecto:

// instrumentation.ts
export async function register() {
  console.log('Server booted at', new Date().toISOString())
}

Qué podés interceptar

Patrón 1: Auto-instrumentación de OpenTelemetry

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { registerOTel } = await import('@vercel/otel')
    registerOTel({ serviceName: 'my-nextjs-app' })
  }
}

El dynamic import es intencional — asegura que módulos solo de Node no se bundleen al runtime de Edge.

Patrón 2: Error tracking con onRequestError

Next.js 15 agregó un export onRequestError. Este hook se dispara cuando se tira un error server-side desde un route handler, server action, server component o middleware.

export async function onRequestError(err, request, context) {
  console.error('Server error:', {
    path: request.path,
    route: context.routePath,
    message: err.message,
  })
}

Construyendo un hook básico de monitoreo manualmente

// instrumentation.ts
export async function register() {
  console.log('Monitoring initialized')
}

export async function onRequestError(err, request, context) {
  const payload = {
    timestamp: new Date().toISOString(),
    message: err.message,
    stack: err.stack,
    route: context.routePath,
    method: request.method,
  }
  fetch(process.env.MONITORING_WEBHOOK_URL!, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(payload),
  }).catch(() => {})
}

Aprox 20 líneas. No es elegante — sin grouping, rate limiting, dashboards, ni alerting — pero es funcional.

Por qué una herramienta dedicada ahorra tiempo

El ejemplo mínimo funciona para "los errores caen en un webhook". En el momento que querés cualquiera de estas cosas, el line count explota: agrupación de errores, rate limiting, dashboards, cálculo de P50/P95/P99, alerting (Slack, email, WhatsApp), checks de uptime externos, monitoreo multi-región, soporte de source maps. Cada uno es de unos días a una semana de trabajo de ingeniería.

Ejemplo con Nurbak Watch

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

export async function register() {
  initWatch({
    apiKey: process.env.NURBAK_WATCH_KEY,
    sampleRate: 1.0,
    ignoreRoutes: ['/api/health'],
  })
}

export const onRequestError = async (err, request, context) => {
  const { reportError } = await import('@nurbak/watch')
  reportError(err, { request, context })
}

Esto maneja monitoreo de uptime, tracking de latencia interna, tasas de error y alerting. Auto-descubre cada ruta API en tu app.

Errores comunes

  • Importar módulos de Node en el top del archivo. Usá dynamic await import() guardado por process.env.NEXT_RUNTIME === 'nodejs'.
  • Hacer trabajo async que bloquea register(). Hace los cold starts más lentos.
  • Dejar que el monitoreo tire excepciones. Wrappealo en try/catch.
  • Olvidar onRequestError. register corre una vez, onRequestError corre por cada error.
  • Shippear PII en payloads de error. Limpiá cookies, headers de auth y bodies antes de forwardear externamente.

Conclusión

instrumentation.ts es la respuesta correcta para monitoreo Next.js. Reemplaza los APM agents tradicionales, funciona en serverless y te da un solo lugar para conectar todo. Si tus necesidades son simples, construilo manual en 20-50 líneas. Si necesitás algo más allá del reporte básico de errores, usá una herramienta dedicada.

Probá Nurbak Watch:empezá gratis — 5 líneas en instrumentation.ts, 3 endpoints, sin tarjeta.

Artículos relacionados