Инструментирование (Instrumentation)

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

Конвенция

Для настройки инструментирования создайте файл 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 для полной реализации.

Важно знать

• Эта функция является экспериментальной. Для её использования необходимо явно включить её, указав experimental.instrumentationHook = true; в вашем next.config.js.
• Файл 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')
  }
}