如何設定 Instrumentation

Instrumentation 是使用程式碼將監控和記錄工具整合到應用程式中的過程。這讓您可以追蹤應用程式的效能和行為，並在生產環境中除錯問題。

慣例

要設定 instrumentation，請在專案的根目錄中建立 instrumentation.ts|js 檔案（如果使用 src 資料夾，則放在該資料夾內）。

然後在檔案中匯出一個 register 函式。當新的 Next.js 伺服器實例初始化時，此函式將被呼叫一次。

例如，要搭配 OpenTelemetry 和 @vercel/otel 使用 Next.js：

import { registerOTel } from '@vercel/otel'

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

完整實作請參考 Next.js with OpenTelemetry 範例。

須知事項：

• instrumentation 檔案應位於專案根目錄，而不是 app 或 pages 目錄內。如果使用 src 資料夾，請將檔案放在 src 內與 pages 和 app 同級的位置。
• 如果您使用 pageExtensions 設定選項 來新增副檔名，則也需要更新 instrumentation 檔名以匹配。

範例

匯入具有副作用 (side effects) 的檔案

有時，由於檔案會產生的副作用，在程式碼中匯入該檔案可能很有用。例如，您可能匯入一個定義了一組全域變數的檔案，但從未在程式碼中明確使用該匯入的檔案。您仍然可以存取該套件宣告的全域變數。

我們建議在 register 函式中使用 JavaScript import 語法來匯入檔案。以下範例展示了在 register 函式中使用 import 的基本用法：

export async function register() {
  await import('package-with-side-effect')
}

須知事項：

我們建議從 register 函式中匯入檔案，而不是在檔案頂部全域匯入。這樣做可以將所有副作用集中到程式碼中的一個位置，避免因在檔案頂部全域匯入而產生意外的後果。

匯入執行環境 (runtime) 特定程式碼

Next.js 在所有環境中都會呼叫 register 函式，因此有條件地匯入不支援特定執行環境（例如 Edge 或 Node.js）的程式碼非常重要。您可以使用 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')
  }
}