Skip to main content

Instrumentation

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

公约​

要设置 instrumentation, 请在项目的根目录中创建 `instrumentation.ts|js 文件，如果使用src文件夹，则在其中创建。

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

例如，要将 Next.js 与OpenTelemetry 和 @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 with OpenTelemetry 示例以获取完整的实现。

您需要知道

  • 此功能是实验性的。要使用它，您必须通过在next.config.js中定义experimental.instrumentationHook = true;来明确选择加入。
  • instrumentation文件应位于项目的根目录中，而不是在app 或 pages文件夹中。如果您使用src文件夹, 那么请将文件放在src中，旁边是pages 和 app。
  • 如果您使用pageExtensions配置选项添加后缀，则还需要更新instrumentation文件名以匹配。

示例​

导入具有副作用的文件​

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

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

export async function register() {
  await import("package-with-side-effect");
}
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");
  }
}
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./instrumentation-node");
  }

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