跳至內容
Pages RouterAPI 參考文件instrumentation.js

instrumentation.js

instrumentation.js|ts 檔案用於將可觀測性工具整合到您的應用程式中，讓您可以追蹤效能和行為，並偵錯生產環境中的問題。

若要使用它，請將檔案放置在應用程式的根目錄，或者如果使用 src 資料夾，則放置在其中。

匯出

register (選用)

此檔案匯出一個 register 函式，該函式在新 Next.js 伺服器實例啟動時會被呼叫一次。register 可以是一個非同步函式。

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

onRequestError (選用)

您可以選擇性地匯出 onRequestError 函式，以將伺服器錯誤追蹤到任何自訂可觀測性供應商。

  • 如果您在 onRequestError 中執行任何非同步任務，請確保它們已被等待。當 Next.js 伺服器捕獲到錯誤時，將會觸發 onRequestError。
  • error 實例可能不是原始拋出的錯誤實例，因為如果在伺服器元件渲染期間遇到錯誤，它可能會被 React 處理。如果發生這種情況，您可以使用錯誤上的 digest 屬性來識別實際的錯誤類型。
instrumentation.ts
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',
    },
  })
}

參數

此函式接受三個參數：error、request 和 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。
  • request：與錯誤相關聯的唯讀請求資訊。
  • context：錯誤發生的上下文。這可以是路由器的類型（App 或 Pages Router），和/或（伺服器元件 ('render')、路由處理器 ('route')、伺服器行為 ('action') 或中介軟體 ('middleware')）。

指定執行階段

instrumentation.js 檔案在 Node.js 和 Edge 執行階段中都可運作，但是，您可以使用 process.env.NEXT_RUNTIME 來指定特定的執行階段。

instrumentation.js
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-RC引入 onRequestError，instrumentation 穩定
v14.0.4Turbopack 支援 instrumentation
v13.2.0instrumentation 作為實驗性功能引入