Настройка инструментирования

Инструментирование — это процесс использования кода для интеграции инструментов мониторинга и логирования в ваше приложение. Это позволяет отслеживать производительность и поведение приложения, а также находить ошибки в рабочей среде.

Конвенция

Для настройки инструментирования создайте файл instrumentation.ts|js в корневой директории вашего проекта (или внутри папки src, если она используется).

Затем экспортируйте функцию register в этом файле. Эта функция будет вызвана один раз при инициализации нового экземпляра сервера Next.js.

Например, для использования Next.js с OpenTelemetry и @vercel/otel:

import { registerOTel } from '@vercel/otel'

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

import { registerOTel } from '@vercel/otel'

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

Полную реализацию смотрите в примере Next.js с OpenTelemetry.

Полезно знать:

• Файл instrumentation должен находиться в корне проекта, а не внутри директорий app или pages. Если вы используете папку src, разместите файл внутри src рядом с pages и app.
• Если вы используете опцию конфигурации pageExtensions для добавления суффикса, вам также потребуется обновить имя файла instrumentation, чтобы оно соответствовало.

Примеры

Импорт файлов с побочными эффектами

Иногда может быть полезно импортировать файл в ваш код из-за побочных эффектов, которые он вызывает. Например, вы можете импортировать файл, который определяет набор глобальных переменных, но никогда явно не использовать импортированный файл в вашем коде. У вас всё равно будет доступ к глобальным переменным, объявленным в пакете.

Мы рекомендуем импортировать файлы с использованием синтаксиса JavaScript import внутри вашей функции register. Следующий пример демонстрирует базовое использование import в функции register:

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

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

Полезно знать:

Мы рекомендуем импортировать файл изнутри функции register, а не в верхней части файла. Это позволяет собрать все побочные эффекты в одном месте вашего кода и избежать непредвиденных последствий от глобального импорта в начале файла.

Импорт кода для конкретной среды выполнения

Next.js вызывает функцию register во всех средах, поэтому важно условно импортировать любой код, который не поддерживает определённые среды выполнения (например, Edge или Node.js). Вы можете использовать переменную окружения NEXT_RUNTIME для определения текущей среды:

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