Skip to main content

instrumentation.js

instrumentation.js|ts 文件用于将可观察性工具集成到你的应用中，允许你跟踪性能和行为，并调试生产中的问题。

¥The instrumentation.js|ts file is used to integrate observability tools into your application, allowing you to track the performance and behavior, and to debug issues in production.

要使用它，请将文件放在应用的根目录中，或者如果使用的话，放在 src 文件夹 中。

¥To use it, place the file in the root of your application or inside a src folder if using one.

导出​

¥Exports

register（可选）​

¥register (optional)

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

¥The file exports a register function that is called once when a new Next.js server instance is initiated. register can be an async function.

import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel('next-app')
}
import { registerOTel } from '@vercel/otel'

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

onRequestError（可选）​

¥onRequestError (optional)

你可以选择将 onRequestError 函数导出到任何自定义可观察性提供程序以跟踪服务器错误。

¥You can optionally export an onRequestError function to track server errors to any custom observability provider.

  • 如果你在 onRequestError 中运行任何异步任务，请确保它们已被等待。当 Next.js 服务器捕获错误时，将触发 onRequestError。

    ¥If you're running any async tasks in onRequestError, make sure they're awaited. onRequestError will be triggered when the Next.js server captures the error.

  • error 实例可能不是抛出的原始错误实例，因为如果在服务器组件渲染期间遇到它，React 可能会处理它。如果发生这种情况，你可以在错误上使用 digest 属性来识别实际的错误类型。

    ¥The error instance might not be the original error instance thrown, as it may be processed by React if encountered during Server Components rendering. If this happens, you can use digest property on an error to identify the actual error type.

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

参数​

¥Parameters

该函数接受三个参数：error、request 和 context。

¥The function accepts three parameters: error, request, and context.

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 }
  },
  context: {
    routerKind: 'Pages Router' | 'App Router' // the router type
    routePath: string // the route file path, e.g. /app/blog/[dynamic]
    routeType: 'render' | 'route' | 'action' | 'middleware' // 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）以及 digest 属性，它是错误的唯一 ID。

    ¥error: The caught error itself (type is always Error), and a digest property which is the unique ID of the error.

  • request：与错误相关的只读请求信息。

    ¥request: Read-only request information associated with the error.

  • context：发生错误的上下文。这可以是路由的类型（应用或页面路由），和/或（服务器组件（'render'）、路由处理程序（'route'）、服务器操作（'action'）或中间件（'middleware'））。

    ¥context: The context in which the error occurred. This can be the type of router (App or Pages Router), and/or (Server Components ('render'), Route Handlers ('route'), Server Actions ('action'), or Middleware ('middleware')).

指定运行时​

¥Specifying the runtime

instrumentation.js 文件在 Node.js 和 Edge 运行时中均可用，但是，你可以使用 process.env.NEXT_RUNTIME 来定位特定的运行时。

¥The instrumentation.js file works in both the Node.js and Edge runtime, however, you can use process.env.NEXT_RUNTIME to target a specific 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')
  }
}

版本历史​

¥Version History

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