跳到内容

OpenTelemetry

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

随着应用程序变得越来越复杂,识别和诊断可能出现的问题变得越来越困难。通过利用可观测性工具(例如日志记录和指标),开发人员可以深入了解其应用程序的行为,并确定需要优化的领域。借助可观测性,开发人员可以在问题变成重大问题之前主动解决问题,并提供更好的用户体验。因此,强烈建议在您的 Next.js 应用程序中使用可观测性,以提高性能、优化资源并增强用户体验。

我们建议使用 OpenTelemetry 来检测您的应用程序。这是一种与平台无关的应用程序检测方式,使您无需更改代码即可更改可观测性提供商。阅读 官方 OpenTelemetry 文档 以获取有关 OpenTelemetry 及其工作原理的更多信息。

本文档在通篇中使用诸如SpanTraceExporter之类的术语,所有这些都可以在 OpenTelemetry 可观测性入门指南 中找到。

Next.js 开箱即用地支持 OpenTelemetry 检测,这意味着我们已经检测了 Next.js 本身。当您启用 OpenTelemetry 时,我们将自动将您的所有代码(例如 getStaticProps)包装在带有有用属性的span中。

开始使用

OpenTelemetry 是可扩展的,但正确设置它可能非常繁琐。这就是为什么我们准备了一个包 @vercel/otel,以帮助您快速入门。

使用 @vercel/otel

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

终端
npm install @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation

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

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

请参阅 @vercel/otel 文档 以获取其他配置选项。

须知:

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

手动 OpenTelemetry 配置

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

首先,您需要安装 OpenTelemetry 包

终端
npm install @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http

现在您可以在 instrumentation.ts 中初始化 NodeSDK。与 @vercel/otel 不同,NodeSDK 与 Edge 运行时不兼容,因此您需要确保仅在 process.env.NEXT_RUNTIME === 'nodejs' 时导入它们。我们建议创建一个新文件 instrumentation.node.ts,仅在使用 Node 时有条件地导入该文件

instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation.node.ts')
  }
}
instrumentation.node.ts
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { Resource } 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: new Resource({
    [ATTR_SERVICE_NAME]: 'next-app',
  }),
  spanProcessor: new SimpleSpanProcessor(new OTLPTraceExporter()),
})
sdk.start()

这样做等同于使用 @vercel/otel,但可以修改和扩展 @vercel/otel 未公开的某些功能。如果需要 Edge 运行时支持,您将必须使用 @vercel/otel

测试您的检测

您需要一个带有兼容后端的 OpenTelemetry 收集器,以在本地测试 OpenTelemetry 跟踪。我们建议使用我们的 OpenTelemetry 开发环境

如果一切正常,您应该能够看到标记为 GET /requested/pathname 的根服务器 span。来自该特定跟踪的所有其他 span 将嵌套在它下面。

Next.js 跟踪的 span 比默认发出的 span 更多。要查看更多 span,您必须设置 NEXT_OTEL_VERBOSE=1

部署

使用 OpenTelemetry Collector

当您使用 OpenTelemetry Collector 部署时,可以使用 @vercel/otel。它在 Vercel 和自托管时都可以工作。

在 Vercel 上部署

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

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

自托管

部署到其他平台也很简单。您将需要启动自己的 OpenTelemetry Collector 以接收和处理来自 Next.js 应用程序的遥测数据。

为此,请按照 OpenTelemetry Collector 入门指南 进行操作,该指南将引导您完成设置收集器并将其配置为接收来自 Next.js 应用程序的数据。

一旦您的收集器启动并运行,您就可以按照各自的部署指南将 Next.js 应用程序部署到您选择的平台。

自定义导出器

OpenTelemetry Collector 不是必需的。您可以将自定义 OpenTelemetry 导出器与 @vercel/otel手动 OpenTelemetry 配置 一起使用。

自定义 Span

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

终端
npm install @opentelemetry/api

以下示例演示了一个获取 GitHub 星星的函数,并添加了一个自定义 fetchGithubStars span 以跟踪获取请求的结果

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,并且它们应该正确添加到导出的跟踪中。

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
    • 这是应用程序路由器使用的内部值。
    • 您可以将其视为特殊文件(如 page.tslayout.tsloading.ts 等)的路由
    • 仅当与 next.route 配对使用时,它才能用作唯一标识符,因为 /layout 可以用于标识 /(groupA)/layout.ts/(groupB)/layout.ts

[http.method] [next.route]

  • next.span_typeBaseServer.handleRequest

此 span 表示每个传入 Next.js 应用程序的请求的根 span。它跟踪请求的 HTTP 方法、路由、目标和状态代码。

属性

渲染路由 (app) [next.route]

  • next.span_typeAppRender.getBodyResult

此 span 表示在应用程序路由器中渲染路由的过程。

属性

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

fetch [http.method] [http.url]

  • next.span_typeAppRender.fetch

此 span 表示在您的代码中执行的 fetch 请求。

属性

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

执行 API 路由 (app) [next.route]

  • next.span_typeAppRouteRouteHandlers.runHandler

此 span 表示在应用程序路由器中执行 API 路由处理程序。

属性

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

getServerSideProps [next.route]

  • next.span_typeRender.getServerSideProps

此 span 表示为特定路由执行 getServerSideProps

属性

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

getStaticProps [next.route]

  • next.span_typeRender.getStaticProps

此 span 表示为特定路由执行 getStaticProps

属性

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

渲染路由 (pages) [next.route]

  • next.span_typeRender.renderDocument

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

属性

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

generateMetadata [next.page]

  • next.span_typeResolveMetadata.generateMetadata

此 span 表示为特定页面生成元数据的过程(单个路由可以有多个此类 span)。

属性

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

解析页面组件

  • next.span_typeNextNodeServer.findPageComponents

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

属性

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

解析段模块

  • next.span_typeNextNodeServer.getLayoutOrPageModule

此 span 表示加载布局或页面的代码模块。

属性

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

开始响应

  • next.span_typeNextNodeServer.startResponse

此零长度 span 表示响应中发送第一个字节的时间。