instrumentation.js

instrumentation.js|ts 文件用于将可观测性工具集成到您的应用程序中，使您能够跟踪其性能和行为，并调试生产环境中的问题。

要使用它，请将文件放置在应用程序的根目录，如果使用 src 文件夹，则放置在该文件夹内。

导出

`register` (可选)

该文件导出一个 register 函数，当新的 Next.js 服务器实例启动时，该函数会且仅会调用一次。register 可以是一个异步函数。

typescript

import { registerOTel } from '@vercel/otel'

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

javascript

import { registerOTel } from '@vercel/otel'

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

`onRequestError` (可选)

您可以有选择地导出一个 onRequestError 函数，以将服务器错误跟踪到任何自定义可观测性提供商。

如果您在 onRequestError 中运行任何异步任务，请确保它们被 await。当 Next.js 服务器捕获到错误时，onRequestError 将会触发。
error 实例可能不是抛出的原始错误实例，因为如果在服务器组件渲染期间遇到错误，它可能会被 React 处理。如果发生这种情况，您可以使用错误的 digest 属性来识别实际的错误类型。

typescript

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

javascript

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。

typescript

export function onRequestError(
  error: { digest: string } & Error,
  request: {
    path: string // resource path, e.g. /blog?name=foo
    method: string // request method. e.g. GET, POST, etc
    headers: { [key: string]: string | string[] }
  },
  context: {
    routerKind: 'Pages Router' | 'App Router' // the router type
    routePath: string // the route file path, e.g. /app/blog/[dynamic]
    routeType: 'render' | 'route' | 'action' | 'proxy' // the context in which the error occurred
    renderSource:
      | 'react-server-components'
      | 'react-server-components-payload'
      | 'server-rendering'
    revalidateReason: 'on-demand' | 'stale' | undefined // undefined is a normal request without revalidation
    renderType: 'dynamic' | 'dynamic-resume' // 'dynamic-resume' for PPR
  }
): void | Promise<void>

error：捕获到的错误本身（类型始终为 Error），以及一个表示错误唯一 ID 的 digest 属性。
request：与错误相关的只读请求信息。
context：错误发生的上下文。这可以是路由类型（App Router 或 Pages Router），和/或（服务器组件 ('render')、路由处理器 ('route')、服务器动作 ('action') 或代理 ('proxy'))。

指定运行时

instrumentation.js 文件可以在 Node.js 和 Edge 运行时环境中工作，但是，您可以使用 process.env.NEXT_RUNTIME 来针对特定的运行时环境。

javascript

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

版本历史

版本	变更
`v15.0.0`	`onRequestError` 引入，`instrumentation` 稳定
`v14.0.4`	Turbopack 对 `instrumentation` 的支持
`v13.2.0`	`instrumentation` 作为实验性功能引入

instrumentation.js|ts 文件用于将可观测性工具集成到您的应用程序中，使您能够跟踪其性能和行为，并调试生产环境中的问题。

要使用它，请将文件放置在应用程序的根目录，如果使用 src 文件夹，则放置在该文件夹内。

导出

`register` (可选)

该文件导出一个 register 函数，当新的 Next.js 服务器实例启动时，该函数会且仅会调用一次。register 可以是一个异步函数。

typescript

import { registerOTel } from '@vercel/otel'

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

javascript

import { registerOTel } from '@vercel/otel'

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

`onRequestError` (可选)

您可以有选择地导出一个 onRequestError 函数，以将服务器错误跟踪到任何自定义可观测性提供商。

如果您在 onRequestError 中运行任何异步任务，请确保它们被 await。当 Next.js 服务器捕获到错误时，onRequestError 将会触发。
error 实例可能不是抛出的原始错误实例，因为如果在服务器组件渲染期间遇到错误，它可能会被 React 处理。如果发生这种情况，您可以使用错误的 digest 属性来识别实际的错误类型。

typescript

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

javascript

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。

typescript

export function onRequestError(
  error: { digest: string } & Error,
  request: {
    path: string // resource path, e.g. /blog?name=foo
    method: string // request method. e.g. GET, POST, etc
    headers: { [key: string]: string | string[] }
  },
  context: {
    routerKind: 'Pages Router' | 'App Router' // the router type
    routePath: string // the route file path, e.g. /app/blog/[dynamic]
    routeType: 'render' | 'route' | 'action' | 'proxy' // the context in which the error occurred
    renderSource:
      | 'react-server-components'
      | 'react-server-components-payload'
      | 'server-rendering'
    revalidateReason: 'on-demand' | 'stale' | undefined // undefined is a normal request without revalidation
    renderType: 'dynamic' | 'dynamic-resume' // 'dynamic-resume' for PPR
  }
): void | Promise<void>

error：捕获到的错误本身（类型始终为 Error），以及一个表示错误唯一 ID 的 digest 属性。
request：与错误相关的只读请求信息。
context：错误发生的上下文。这可以是路由类型（App Router 或 Pages Router），和/或（服务器组件 ('render')、路由处理器 ('route')、服务器动作 ('action') 或代理 ('proxy'))。

指定运行时

instrumentation.js 文件可以在 Node.js 和 Edge 运行时环境中工作，但是，您可以使用 process.env.NEXT_RUNTIME 来针对特定的运行时环境。

javascript

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

版本历史

版本	变更
`v15.0.0`	`onRequestError` 引入，`instrumentation` 稳定
`v14.0.4`	Turbopack 对 `instrumentation` 的支持
`v13.2.0`	`instrumentation` 作为实验性功能引入

文档导航

导出

register (可选)

onRequestError (可选)

参数

指定运行时

版本历史

导出

register (可选)

onRequestError (可选)

参数

指定运行时

版本历史

`register` (可选)

`onRequestError` (可选)

`register` (可选)

`onRequestError` (可选)