Instrumentación

Si exportas una función llamada register desde un archivo instrumentation.ts (o .js) en el directorio raíz de tu proyecto (o dentro de la carpeta src si estás usando una), llamaremos a esa función cada vez que se inicie una nueva instancia del servidor Next.js.

Es bueno saber

• 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.
• Hemos creado un ejemplo básico with-opentelemetry que puedes usar.

Cuando tu función register sea desplegada, será llamada en cada arranque en frío (pero exactamente una vez en cada entorno).

A veces puede ser útil importar un archivo en tu código debido a los efectos secundarios que causará. 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.

Puedes importar archivos con efectos secundarios en instrumentation.ts, lo cual podrías querer usar en tu función register como se muestra en el siguiente ejemplo:

import { init } from 'package-init'

export function register() {
  init()
}

import { init } from 'package-init'

export function register() {
  init()
}

Sin embargo, recomendamos importar archivos con efectos secundarios usando import desde 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')
}

Al hacer esto, puedes colocar todos tus efectos secundarios en un solo lugar en tu código y evitar consecuencias no deseadas al importar archivos.

Llamamos a register en todos los entornos, por lo que es necesario importar condicionalmente cualquier código que no sea compatible tanto con edge como con nodejs. Puedes usar la variable de entorno NEXT_RUNTIME para obtener el entorno actual. Importar un código específico del entorno se vería así:

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')
  }
}