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

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

Конвенция

Для настройки инструментария создайте файл 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')
  }
}