Инструментарий

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

Конвенция

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

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

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

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

Важно знать:

Мы рекомендуем импортировать файл из функции 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')
  }
}