如何设置仪表化 (Instrumentation)

仪表化 (Instrumentation) 是通过代码将监控和日志工具集成到应用程序中的过程。这使您能够追踪应用的性能和行为，并在生产环境中调试问题。

约定 (Convention)

要设置仪表化 (Instrumentation)，请在项目的根目录（如果使用了 src 文件夹，则放在该文件夹内）创建 instrumentation.ts|js 文件。

然后，在该文件中导出一个 register 函数。当新的 Next.js 服务器实例启动时，该函数将被调用一次。

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

import { registerOTel } from '@vercel/otel'

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

完整实现请参考 Next.js with OpenTelemetry 示例。

须知:

• instrumentation 文件应位于项目根目录，而不是 app 或 pages 目录内。如果使用了 src 文件夹，请将文件放在 src 内与 pages 和 app 同级的位置。
• 如果使用了 pageExtensions 配置选项 添加后缀，也需要相应更新 instrumentation 文件名以匹配。

示例 (Examples)

导入具有副作用 (side effects) 的文件

有时，由于文件导入会产生的副作用，在代码中导入文件可能很有用。例如，您可能导入一个定义了全局变量的文件，但从未在代码中显式使用该导入文件。您仍然可以访问该包声明的全局变量。

我们建议在 register 函数中使用 JavaScript import 语法导入文件。以下示例展示了在 register 函数中使用 import 的基本用法：

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

须知:

我们建议在 register 函数内部导入文件，而不是在文件顶部全局导入。这样做可以将所有副作用代码集中在一个位置，避免在文件顶部全局导入可能导致的意外后果。

导入运行时特定代码 (Runtime-specific code)

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