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

Если вы экспортируете функцию с именем register из файла instrumentation.ts (или .js) в корневой директории вашего проекта (или внутри папки src, если она используется), мы будем вызывать эту функцию при каждой инициализации нового экземпляра сервера Next.js.

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

• Эта функция является экспериментальной. Для её использования необходимо явно указать experimental.instrumentationHook = true; в вашем next.config.js.
• Файл instrumentation должен находиться в корне проекта, а не внутри директорий app или pages. Если вы используете папку src, разместите файл внутри src рядом с pages и app.
• Если вы используете опцию конфигурации pageExtensions для добавления суффикса, вам также потребуется обновить имя файла instrumentation, чтобы оно соответствовало.
• Мы создали базовый пример with-opentelemetry, который вы можете использовать.

Когда ваша функция register будет развёрнута, она будет вызываться при каждом холодном запуске (но ровно один раз в каждом окружении).

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

Вы можете импортировать файлы с побочными эффектами в instrumentation.ts, которые могут быть полезны в вашей функции register, как показано в следующем примере:

import { init } from 'package-init'

export function register() {
  init()
}

import { init } from 'package-init'

export function register() {
  init()
}

Однако мы рекомендуем импортировать файлы с побочными эффектами с помощью 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 во всех окружениях, поэтому необходимо условно импортировать любой код, который не поддерживает одновременно edge и nodejs. Вы можете использовать переменную окружения 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')
  }
}