NNext.js 中文网 GitHub

如何使用 OpenTelemetry 为 Next.js 应用添加检测

了解如何使用 OpenTelemetry 为 Next.js 应用添加检测。

可观测性对于理解和优化 Next.js 应用的行为与性能至关重要。

随着应用变得越来越复杂,识别和诊断可能出现的问题也变得越来越困难。通过利用日志和指标等可观测性工具,开发者可以深入了解应用的行为并找出可以优化的地方。借助可观测性,开发者可以在问题演变成重大故障之前主动解决它们,并提供更好的用户体验。因此,强烈建议在 Next.js 应用中使用可观测性,以改善性能、优化资源并提升用户体验。

我们建议使用 OpenTelemetry 来为你的应用进行插桩。 这是一种与平台无关的插桩方式,让你无需修改代码即可更换可观测性提供商。 阅读 OpenTelemetry 官方文档以了解更多关于 OpenTelemetry 及其工作原理的信息。

本文档通篇使用了 Span、Trace 或 Exporter 等术语,这些都可以在 OpenTelemetry 可观测性入门中找到。

Next.js 开箱即用地支持 OpenTelemetry 插桩,这意味着我们已经对 Next.js 自身进行了插桩。

当你启用 OpenTelemetry 时,我们会自动将所有类似 getStaticProps 的代码包裹在带有实用属性的 span 中。

入门#

OpenTelemetry 具有可扩展性,但正确配置它可能相当繁琐。 因此,我们准备了一个 @vercel/otel 包,帮助你快速上手。

使用 @vercel/otel#

要开始使用,请安装以下包:

bash · pnpm
pnpm add @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation
bash · npm
npm install @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation
bash · yarn
yarn add @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation
bash · bun
bun add @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation

接下来,在项目的根目录(如果使用 src 文件夹,则在其内部)创建一个自定义的 instrumentation.ts(或 .js)文件:

接下来,在项目的根目录(如果使用 src 文件夹,则在其内部)创建一个自定义的 instrumentation.ts(或 .js)文件:

your-project/instrumentation.ts
import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel({ serviceName: 'next-app' })
}
your-project/instrumentation.js
import { registerOTel } from '@vercel/otel'

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

有关更多配置选项,请参阅 @vercel/otel 文档。

小知识:

  • instrumentation 文件应位于项目的根目录,而不是 app 或 pages 目录内。如果你使用 src 文件夹,则将该文件放在 src 中,与 pages 和 app 并列。
  • 如果你使用 pageExtensions 配置选项来添加后缀,则还需要相应地更新 instrumentation 文件名。
  • 我们创建了一个基础的 with-opentelemetry 示例,你可以参考使用。

小知识:

  • instrumentation 文件应位于项目的根目录,而不是 app 或 pages 目录内。如果你使用 src 文件夹,则将该文件放在 src 中,与 pages 和 app 并列。
  • 如果你使用 pageExtensions 配置选项来添加后缀,则还需要相应地更新 instrumentation 文件名。
  • 我们创建了一个基础的 with-opentelemetry 示例,你可以参考使用。

手动配置 OpenTelemetry#

@vercel/otel 包提供了许多配置选项,应该能满足大多数常见用例。但如果它不适合你的需求,你可以手动配置 OpenTelemetry。

首先,你需要安装 OpenTelemetry 相关的包:

bash · pnpm
pnpm add @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http
bash · npm
npm install @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http
bash · yarn
yarn add @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http
bash · bun
bun add @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http

现在你可以在 instrumentation.ts 中初始化 NodeSDK。 与 @vercel/otel 不同,NodeSDK 不兼容 edge runtime,因此你需要确保仅在 process.env.NEXT_RUNTIME === 'nodejs' 时才导入它们。我们建议创建一个新文件 instrumentation.node.ts,仅在 Node.js 环境下有条件地导入它:

instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation.node.ts')
  }
}
instrumentation.js
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation.node.js')
  }
}
instrumentation.node.ts
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { resourceFromAttributes } from '@opentelemetry/resources'
import { NodeSDK } from '@opentelemetry/sdk-node'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node'
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: 'next-app',
  }),
  spanProcessor: new SimpleSpanProcessor(new OTLPTraceExporter()),
})
sdk.start()
instrumentation.node.js
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { resourceFromAttributes } from '@opentelemetry/resources'
import { NodeSDK } from '@opentelemetry/sdk-node'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node'
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: 'next-app',
  }),
  spanProcessor: new SimpleSpanProcessor(new OTLPTraceExporter()),
})
sdk.start()

这样做与使用 @vercel/otel 是等效的,但你可以修改和扩展一些 @vercel/otel 未公开的功能。如果需要 edge runtime 支持,则必须使用 @vercel/otel。

测试你的插桩#

你需要一个带有兼容后端的 OpenTelemetry Collector,才能在本地测试 OpenTelemetry trace。 我们建议使用我们的 OpenTelemetry 开发环境。

如果一切正常,你应该能看到标记为 GET /requested/pathname 的根服务端 span。 该 trace 中的所有其他 span 都将嵌套在其下。

Next.js 会追踪比默认发出数量更多的 span。 要查看更多 span,你必须设置 NEXT_OTEL_VERBOSE=1。

部署#

使用 OpenTelemetry Collector#

当你使用 OpenTelemetry Collector 进行部署时,可以使用 @vercel/otel。 它既可以在 Vercel 上运行,也可以在自托管环境中使用。

在 Vercel 上部署#

我们确保 OpenTelemetry 在 Vercel 上开箱即用。

按照 Vercel 文档将你的项目连接到可观测性提供商。

自托管#

部署到其他平台同样简单。你需要启动自己的 OpenTelemetry Collector,以接收和处理来自 Next.js 应用的遥测数据。

为此,请遵循 OpenTelemetry Collector 入门指南,该指南将引导你设置 collector 并配置它以接收来自 Next.js 应用的数据。

一旦 collector 启动并运行,你就可以按照所选平台各自的部署指南,将 Next.js 应用部署到该平台。

自定义 Exporter#

OpenTelemetry Collector 并非必需。你可以将自定义 OpenTelemetry exporter 与 @vercel/otel 或手动 OpenTelemetry 配置一起使用。

自定义 Span#

你可以使用 OpenTelemetry API添加自定义 span。

bash · pnpm
pnpm add @opentelemetry/api
bash · npm
npm install @opentelemetry/api
bash · yarn
yarn add @opentelemetry/api
bash · bun
bun add @opentelemetry/api

以下示例演示了一个获取 GitHub star 数的函数,它添加了一个自定义的 fetchGithubStars span 来跟踪该 fetch 请求的结果:

ts
import { trace } from '@opentelemetry/api'

export async function fetchGithubStars() {
  return await trace
    .getTracer('nextjs-example')
    .startActiveSpan('fetchGithubStars', async (span) => {
      try {
        return await getValue()
      } finally {
        span.end()
      }
    })
}

register 函数将在你的代码于新环境中运行之前执行。 之后,你在处理请求时创建的 span 会被添加到该请求的 trace 中。

小知识:在 instrumentation 文件加载期间或 register 内部创建的 span 不会自动加入请求的 trace。在 tracer provider 安装之前启动的 span(例如,在 registerOTel 运行之前的文件顶层)不会被记录,而在 registerOTel(或你的 OpenTelemetry SDK)启动之后、在 register 内部启动的 span 通常会成为独立的根 trace。要将某项工作作为请求的一部分进行追踪,请在用于处理请求的代码中创建 span,例如在渲染页面时,或在 Route Handler 或 API Route 中。

Next.js 中的默认 Span#

Next.js 会自动为你插桩多个 span,以便对应用性能提供有用的洞察。

span 上的属性遵循 OpenTelemetry 语义约定。我们还在 next 命名空间下添加了一些自定义属性:

  • next.span_name - 与 span 名称重复
  • next.span_type - 每种 span 类型都有唯一的标识符
  • next.route - 请求的路由模式(例如 /[param]/user)。
  • next.rsc (true/false) - 该请求是否为 RSC 请求,例如预取。
  • next.page
    • 这是一个由 App Router 使用的内部值。
    • 你可以将其理解为指向某个特殊文件(如 page.ts、layout.ts、loading.ts 等)的路由
    • 只有与 next.route 配合使用时,它才能作为唯一标识符,因为 /layout 可能同时标识 /(groupA)/layout.ts 和 /(groupB)/layout.ts

[http.method] [next.route]#

  • next.span_type: BaseServer.handleRequest

该 span 表示对 Next.js 应用的每个传入请求的根 span。它记录请求的 HTTP 方法、路由、目标和状态码。

属性:

render route (app) [next.route]#

  • next.span_type: AppRender.getBodyResult.

该 span 表示在 App Router 中渲染路由的过程。

属性:

  • next.span_name
  • next.span_type
  • next.route

validate route (app) [next.route]#

  • next.span_type: AppRender.devValidation

该 span 表示 next dev 在使用 Cache Components 渲染路由后,在后台运行的验证过程。它在响应完成之后运行,因此它自身是一个 trace 的根,并链接到它所验证渲染的 render route (app) [next.route] span。验证渲染的 span 是它的子 span。

属性:

  • next.span_name
  • next.span_type
  • next.route

fetch [http.method] [http.url]#

  • next.span_type: AppRender.fetch

该 span 表示在你的代码中执行的 fetch 请求。

属性:

可以通过在环境中设置 NEXT_OTEL_FETCH_DISABLED=1 来关闭该 span。当你想使用自定义的 fetch 插桩库时,这很有用。

executing api route (app) [next.route]#

  • next.span_type: AppRouteRouteHandlers.runHandler.

该 span 表示在 App Router 中执行 API Route Handler 的过程。

属性:

  • next.span_name
  • next.span_type
  • next.route

getServerSideProps [next.route]#

  • next.span_type: Render.getServerSideProps.

该 span 表示针对特定路由执行 getServerSideProps 的过程。

属性:

  • next.span_name
  • next.span_type
  • next.route

getStaticProps [next.route]#

  • next.span_type: Render.getStaticProps.

该 span 表示针对特定路由执行 getStaticProps 的过程。

属性:

  • next.span_name
  • next.span_type
  • next.route

render route (pages) [next.route]#

  • next.span_type: Render.renderDocument.

该 span 表示为特定路由渲染文档的过程。

属性:

  • next.span_name
  • next.span_type
  • next.route

generateMetadata [next.page]#

  • next.span_type: ResolveMetadata.generateMetadata.

该 span 表示为特定页面生成元数据的过程(单个路由可能有多个这样的 span)。

属性:

  • next.span_name
  • next.span_type
  • next.page

resolve page components#

  • next.span_type: NextNodeServer.findPageComponents.

该 span 表示为特定页面解析页面组件的过程。

属性:

  • next.span_name
  • next.span_type
  • next.route

resolve segment modules#

  • next.span_type: NextNodeServer.getLayoutOrPageModule.

该 span 表示为 layout 或 page 加载代码模块的过程。

属性:

  • next.span_name
  • next.span_type
  • next.segment

start response#

  • next.span_type: NextNodeServer.startResponse.

这个长度为零的 span 表示响应中第一个字节被发送的时刻。

Next.js 中文网