instrumentation.js

El archivo instrumentation.js|ts se utiliza para integrar herramientas de observabilidad en tu aplicación, permitiéndote rastrear el rendimiento y comportamiento, así como depurar problemas en producción.

Para usarlo, coloca el archivo en la raíz de tu aplicación o dentro de una carpeta src si estás utilizando una.

Exportaciones

register (opcional)

El archivo exporta una función register que se llama una vez cuando se inicia una nueva instancia del servidor Next.js. register puede ser una función asíncrona.

import { registerOTel } from '@vercel/otel'

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

onRequestError (opcional)

Puedes exportar opcionalmente una función onRequestError para rastrear errores del servidor en cualquier proveedor de observabilidad personalizado.

• Si estás ejecutando tareas asíncronas en onRequestError, asegúrate de que sean esperadas (awaited). onRequestError se activará cuando el servidor Next.js capture el error.
• La instancia error podría no ser la instancia original del error lanzado, ya que puede ser procesada por React si ocurre durante el renderizado de Componentes del Servidor. Si esto sucede, puedes usar la propiedad digest en un error para identificar el tipo real de error.

import { type Instrumentation } from 'next'

export const onRequestError: Instrumentation.onRequestError = async (
  err,
  request,
  context
) => {
  await fetch('https://.../report-error', {
    method: 'POST',
    body: JSON.stringify({
      message: err.message,
      request,
      context,
    }),
    headers: {
      'Content-Type': 'application/json',
    },
  })
}

Parámetros

La función acepta tres parámetros: error, request y context.

export function onRequestError(
  error: { digest: string } & Error,
  request: {
    path: string // ruta del recurso, ej. /blog?name=foo
    method: string // método de la solicitud, ej. GET, POST, etc
    headers: { [key: string]: string }
  },
  context: {
    routerKind: 'Pages Router' | 'App Router' // tipo de enrutador
    routePath: string // ruta del archivo, ej. /app/blog/[dynamic]
    routeType: 'render' | 'route' | 'action' | 'middleware' // contexto donde ocurrió el error
    renderSource:
      | 'react-server-components'
      | 'react-server-components-payload'
      | 'server-rendering'
    revalidateReason: 'on-demand' | 'stale' | undefined // undefined es una solicitud normal sin revalidación
    renderType: 'dynamic' | 'dynamic-resume' // 'dynamic-resume' para PPR
  }
): void | Promise<void>

• error: El error capturado (el tipo siempre es Error), y una propiedad digest que es el ID único del error.
• request: Información de solo lectura de la solicitud asociada al error.
• context: El contexto en el que ocurrió el error. Puede ser el tipo de enrutador (App o Pages Router), y/o (Componentes del Servidor ('render'), Manejadores de Ruta ('route'), Acciones del Servidor ('action'), o Middleware ('middleware')).

Especificando el runtime

El archivo instrumentation.js funciona tanto en el runtime de Node.js como en Edge, sin embargo, puedes usar process.env.NEXT_RUNTIME para dirigirte a un runtime específico.

export function register() {
  if (process.env.NEXT_RUNTIME === 'edge') {
    return require('./register.edge')
  } else {
    return require('./register.node')
  }
}

export function onRequestError() {
  if (process.env.NEXT_RUNTIME === 'edge') {
    return require('./on-request-error.edge')
  } else {
    return require('./on-request-error.node')
  }
}

Historial de versiones