OpenTelemetry

可觀察性對於理解和最佳化 Next.js 應用程式的行為和效能至關重要。

隨著應用程式變得越來越複雜，識別和診斷可能出現的問題也變得越來越困難。透過利用可觀察性工具，例如日誌記錄和指標，開發人員可以深入了解其應用程式的行為，並找出可最佳化的領域。透過可觀察性，開發人員可以在問題變成重大問題之前主動解決，並提供更好的使用者體驗。因此，強烈建議在您的 Next.js 應用程式中使用可觀察性，以提高效能、最佳化資源並增強使用者體驗。

我們建議使用 OpenTelemetry 來檢測您的應用程式。這是一種與平台無關的方式來檢測應用程式，讓您可以變更可觀察性提供者，而無需變更您的程式碼。請閱讀官方 OpenTelemetry 文件以取得更多關於 OpenTelemetry 及其運作方式的資訊。

本文件在通篇中使用諸如 Span、Trace 或 Exporter 等術語，所有這些都可以在OpenTelemetry 可觀察性入門中找到。

Next.js 支援開箱即用的 OpenTelemetry 檢測，這表示我們已經檢測了 Next.js 本身。當您啟用 OpenTelemetry 時，我們會自動將您的所有程式碼（如 getStaticProps）包裝在具有實用屬性的 spans 中。

開始使用

OpenTelemetry 具有可擴展性，但正確設定它可能會相當冗長。這就是為什麼我們準備了一個套件 @vercel/otel，以協助您快速開始。

使用 @vercel/otel

若要開始使用，請安裝以下套件

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

接下來，在專案的根目錄（或在使用 src 資料夾的情況下，在 src 資料夾內）建立自訂的 instrumentation.ts（或 .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 範例供您使用。

手動 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 Runtime 不相容，因此您需要確保僅在 process.env.NEXT_RUNTIME === 'nodejs' 時才匯入它們。我們建議建立一個新的檔案 instrumentation.node.ts，僅在使用 Node 時才條件式匯入它

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./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 Runtime 支援，您將必須使用 @vercel/otel。

測試您的檢測

您需要一個具有相容後端的 OpenTelemetry 收集器，以在本機測試 OpenTelemetry 追蹤。我們建議使用我們的 OpenTelemetry 開發環境。

如果一切運作良好，您應該能夠看到標記為 GET /requested/pathname 的根伺服器 span。來自該特定追蹤的所有其他 spans 都將巢狀於其下。

Next.js 追蹤的 spans 比預設發出的還多。若要查看更多 spans，您必須設定 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 應用程式部署到您選擇的平台。

自訂 Exporters

OpenTelemetry Collector 不是必要的。您可以將自訂 OpenTelemetry exporter 與@vercel/otel 或手動 OpenTelemetry 設定搭配使用。

自訂 Spans

您可以使用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 函式將在新環境中程式碼執行之前執行。您可以開始建立新的 spans，它們應正確地新增至匯出的追蹤。

Next.js 中的預設 Spans

Next.js 自動為您檢測多個 spans，以提供關於應用程式效能的實用見解。

spans 上的屬性遵循OpenTelemetry 語意慣例。我們也在 next 命名空間下新增了一些自訂屬性

• next.span_name - 重複 span 名稱
• next.span_type - 每個 span 類型都有唯一的識別碼
• next.route - 請求的路由模式（例如，/[param]/user）。
• next.rsc (true/false) - 請求是否為 RSC 請求，例如預先擷取。
• next.page
  • 這是應用程式路由器使用的內部值。
  • 您可以將其視為特殊檔案（如 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 方法、路由、目標和狀態碼。

屬性

• 常見 HTTP 屬性
  • http.method
  • http.status_code
• 伺服器 HTTP 屬性
  • http.route
  • http.target
• next.span_name
• next.span_type
• next.route

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

• next.span_type：AppRender.getBodyResult。

此 span 代表在 app router 中渲染路由的過程。

屬性

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

fetch [http.method] [http.url]

• next.span_type：AppRender.fetch

此 span 代表在您的程式碼中執行的 fetch 請求。

屬性

• 常見 HTTP 屬性
  • http.method
• 用戶端 HTTP 屬性
  • http.url
  • net.peer.name
  • net.peer.port（僅在指定時）
• next.span_name
• next.span_type

可以透過在您的環境中設定 NEXT_OTEL_FETCH_DISABLED=1 來關閉此 span。當您想要使用自訂 fetch 檢測函式庫時，這會很有用。

執行 api 路由 (app) [next.route]

• next.span_type：AppRouteRouteHandlers.runHandler。

此 span 代表在 app router 中執行 API 路由處理器。

屬性

• 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.route]

• next.span_type: Render.renderDocument。

此 span 代表呈現特定路由的文件的過程。

屬性

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

generateMetadata [next.page]產生 metadata [next.page]

• next.span_type: ResolveMetadata.generateMetadata。

此 span 代表為特定頁面產生 metadata 的過程 (單一路由可以有多個此類 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 代表載入版面配置或頁面的程式碼模組。

屬性

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

start response開始回應

• next.span_type: NextNodeServer.startResponse。

此零長度 span 代表回應中第一個位元組已傳送的時間點。