instrumentation.js

Файл instrumentation.js|ts используется для интеграции инструментов мониторинга в ваше приложение, позволяя отслеживать производительность и поведение, а также отлаживать проблемы в продакшене.

Чтобы использовать его, разместите файл в корне вашего приложения или внутри папки src, если она используется.

Экспортируемые элементы

register (опционально)

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

import { registerOTel } from '@vercel/otel'

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

import { registerOTel } from '@vercel/otel'

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

onRequestError (опционально)

Вы можете опционально экспортировать функцию onRequestError для отслеживания серверных ошибок в любом провайдере мониторинга.

• Если вы выполняете какие-либо асинхронные задачи в onRequestError, убедитесь, что они ожидаются. onRequestError будет вызвана, когда сервер Next.js перехватит ошибку.
• Экземпляр error может не быть оригинальным экземпляром ошибки, так как он может быть обработан React, если ошибка возникла во время рендеринга серверных компонентов. В этом случае вы можете использовать свойство digest ошибки для идентификации фактического типа ошибки.

import { type Instrumentation } from 'next'

export const onRequestError: Instrumentation.onRequestError = async (
  err,
  request,
  context
) => {
  await fetch('https://.../report-error', {
    method: 'POST',
    body: JSON.stringify({
      message: err.message,
      request,
      context,
    }),
    headers: {
      'Content-Type': 'application/json',
    },
  })
}

export async function onRequestError(err, request, context) {
  await fetch('https://.../report-error', {
    method: 'POST',
    body: JSON.stringify({
      message: err.message,
      request,
      context,
    }),
    headers: {
      'Content-Type': 'application/json',
    },
  })
}

Параметры

Функция принимает три параметра: error, request и context.

export function onRequestError(
  error: { digest: string } & Error,
  request: {
    path: string // путь к ресурсу, например /blog?name=foo
    method: string // метод запроса, например GET, POST и т.д.
    headers: { [key: string]: string }
  },
  context: {
    routerKind: 'Pages Router' | 'App Router' // тип роутера
    routePath: string // путь к файлу маршрута, например /app/blog/[dynamic]
    routeType: 'render' | 'route' | 'action' | 'middleware' // контекст, в котором произошла ошибка
    renderSource:
      | 'react-server-components'
      | 'react-server-components-payload'
      | 'server-rendering'
    revalidateReason: 'on-demand' | 'stale' | undefined // undefined означает обычный запрос без ревалидации
    renderType: 'dynamic' | 'dynamic-resume' // 'dynamic-resume' для PPR
  }
): void | Promise<void>

• error: Сама перехваченная ошибка (тип всегда Error) и свойство digest, которое является уникальным идентификатором ошибки.
• request: Информация о запросе, связанная с ошибкой (только для чтения).
• context: Контекст, в котором произошла ошибка. Это может быть тип роутера (App или Pages Router) и/или (серверные компоненты ('render'), обработчики маршрутов ('route'), серверные действия ('action') или middleware ('middleware')).

Указание среды выполнения

Файл instrumentation.js работает как в среде выполнения Node.js, так и в Edge, однако вы можете использовать process.env.NEXT_RUNTIME для выбора конкретной среды.

export function register() {
  if (process.env.NEXT_RUNTIME === 'edge') {
    return require('./register.edge')
  } else {
    return require('./register.node')
  }
}

export function onRequestError() {
  if (process.env.NEXT_RUNTIME === 'edge') {
    return require('./on-request-error.edge')
  } else {
    return require('./on-request-error.node')
  }
}

История версий