Cómo configurar la instrumentación

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

Convención

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

Luego, exporte 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')
}

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

Es bueno saberlo:

• El archivo instrumentation debe estar en la raíz de su proyecto y no dentro de los directorios app o pages. Si está utilizando la carpeta src, coloque el archivo dentro de src junto con pages y app.
• Si utiliza la opción de configuración pageExtensions para agregar un sufijo, también deberá actualizar el nombre del archivo instrumentation para que coincida.

Ejemplos

Importar archivos con efectos secundarios

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

Recomendamos importar archivos usando la sintaxis de import de JavaScript dentro de su función register. El siguiente ejemplo demuestra 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')
}

Es bueno saberlo:

Recomendamos importar el archivo desde dentro de la función register, en lugar de hacerlo en la parte superior del archivo. Al hacer esto, puede agrupar todos sus efectos secundarios en un solo lugar en su 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 admita entornos de ejecución específicos (por ejemplo, Edge o Node.js). Puede 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')
  }
}