Skip to main content

仪器仪表

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

¥Instrumentation is the process of using code to integrate monitoring and logging tools into your application. This allows you to track the performance and behavior of your application, and to debug issues in production.

惯例​

¥Convention

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

¥To set up instrumentation, create instrumentation.ts|js file in the root directory of your project (or inside the src folder if using one).

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

¥Then, export a register function in the file. This function will be called once when a new Next.js server instance is initiated.

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

¥For example, to use Next.js with OpenTelemetry and @vercel/otel:

import { registerOTel } from '@vercel/otel'

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

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

请参阅 Next.js 与 OpenTelemetry 示例 了解完整的实现。

¥See the Next.js with OpenTelemetry example for a complete implementation.

很高兴知道

¥Good to know

  • 此功能是实验性的。要使用它，你必须通过在 next.config.js 中定义 experimental.instrumentationHook = true; 来明确选择加入。

    ¥This feature is experimental. To use it, you must explicitly opt in by defining experimental.instrumentationHook = true; in your next.config.js.

  • instrumentation 文件应该位于项目的根目录中，而不是位于 app 或 pages 目录中。如果你使用的是 src 文件夹，请将文件与 pages 和 app 一起放入 src 中。

    ¥The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app.

  • 如果你使用 pageExtensions 配置选项 添加后缀，你还需要更新 instrumentation 文件名以匹配。

    ¥If you use the pageExtensions config option to add a suffix, you will also need to update the instrumentation filename to match.

示例​

¥Examples

导入有副作用的文件​

¥Importing files with side effects

有时，在代码中导入文件可能很有用，因为它会引起副作用。例如，你可以导入一个定义一组全局变量的文件，但永远不要在代码中显式使用导入的文件。你仍然可以访问包已声明的全局变量。

¥Sometimes, it may be useful to import a file in your code because of the side effects it will cause. For example, you might import a file that defines a set of global variables, but never explicitly use the imported file in your code. You would still have access to the global variables the package has declared.

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

¥We recommend importing files using JavaScript import syntax within your register function. The following example demonstrates a basic usage of import in a register function:

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

很高兴知道：

¥Good to know:

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

¥We recommend importing the file from within the register function, rather than at the top of the file. By doing this, you can colocate all of your side effects in one place in your code, and avoid any unintended consequences from importing globally at the top of the file.

导入运行时特定的代码​

¥Importing runtime-specific code

Next.js 在所有环境中调用 register，因此有条件地导入任何不支持特定运行时的代码（例如 Edge 或 Node.js）非常重要。你可以使用 NEXT_RUNTIME 环境变量来获取当前环境：

¥Next.js calls register in all environments, so it's important to conditionally import any code that doesn't support specific runtimes (e.g. Edge or Node.js). You can use the NEXT_RUNTIME environment variable to get the current environment:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}