Instrumentation

Instrumentation 是使用代码将监控和日志记录工具集成到您的应用程序中的过程。这使您可以跟踪应用程序的性能和行为，并在生产环境中调试问题。

约定

要设置 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 文件名以匹配。

示例

导入具有副作用的文件

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

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

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

须知

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

导入运行时特定代码

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