Instrumentación

La instrumentación es el proceso de usar código para integrar herramientas de monitoreo y registro en tu aplicación. Esto te permite rastrear el rendimiento y comportamiento de tu aplicación, así como depurar problemas en producción.

Convención

Para configurar la instrumentación, crea un archivo instrumentation.ts|js en el directorio raíz de tu proyecto (o dentro de la carpeta src si estás usando una).

Luego, exporta una función register en el archivo. Esta función será llamada una vez cuando se inicie una nueva instancia del servidor Next.js.

Por ejemplo, para usar Next.js con OpenTelemetry y @vercel/otel:

import { registerOTel } from '@vercel/otel'

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

import { registerOTel } from '@vercel/otel'

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

Consulta el ejemplo de Next.js con OpenTelemetry para una implementación completa.

Importante

• Esta característica es experimental. Para usarla, debes activarla explícitamente definiendo experimental.instrumentationHook = true; en tu next.config.js.
• El archivo instrumentation debe estar en la raíz de tu proyecto y no dentro de los directorios app o pages. Si usas la carpeta src, coloca el archivo dentro de src junto a pages y app.
• Si usas la opción de configuración pageExtensions para agregar un sufijo, también necesitarás actualizar el nombre del archivo instrumentation para que coincida.

Ejemplos

Importar archivos con efectos secundarios

A veces puede ser útil importar un archivo en tu código debido a los efectos secundarios que causa. Por ejemplo, podrías importar un archivo que define un conjunto de variables globales, pero nunca usar explícitamente el archivo importado en tu código. Aún así tendrías acceso a las variables globales que el paquete ha declarado.

Recomendamos importar archivos usando la sintaxis import de JavaScript dentro de tu función register. El siguiente ejemplo muestra un uso básico de import en una función register:

export async function register() {
  await import('package-with-side-effect')
}

export async function register() {
  await import('package-with-side-effect')
}

Importante:

Recomendamos importar el archivo desde dentro de la función register, en lugar de hacerlo en la parte superior del archivo. Al hacer esto, puedes agrupar todos tus efectos secundarios en un solo lugar en tu código y evitar consecuencias no deseadas al importar globalmente en la parte superior del archivo.

Importar código específico del entorno de ejecución

Next.js llama a register en todos los entornos, por lo que es importante importar condicionalmente cualquier código que no sea compatible con entornos específicos (como Edge o Node.js). Puedes usar la variable de entorno NEXT_RUNTIME para obtener el entorno actual:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}