仪器

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

约定

要设置仪器，请在项目的**根目录**中创建instrumentation.ts|js文件（如果使用，则在src文件夹内）。

然后，在文件中导出一个register函数。此函数将在初始化新的 Next.js 服务器实例时**仅调用一次**。

例如，要将 Next.js 与OpenTelemetry和@vercel/otel一起使用

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

请参阅带有 OpenTelemetry 的 Next.js 示例以获取完整的实现。

需要了解:

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