OpenTelemetry

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

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

我們建議使用 OpenTelemetry 來檢測您的應用程式。這是一種與平台無關的應用程式檢測方法，允許您在不更改程式碼的情況下更改可觀察性供應商。請閱讀OpenTelemetry 官方文件以了解更多關於 OpenTelemetry 及其運作方式的資訊。

本文檔在全文中使用了諸如「Span」、「Trace」或「Exporter」等術語，所有這些都可以在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）檔案

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 與邊緣運行環境不相容，因此您需要確保僅在 process.env.NEXT_RUNTIME === 'nodejs' 時才導入它們。我們建議您建立一個新的檔案 instrumentation.node.ts，僅在使用 Node.js 時才導入。

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 未公開的一些功能。如果需要邊緣運行環境支援，您必須使用 @vercel/otel。

測試您的 instrumentation。

如果一切正常，您應該能夠看到標記為 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 收集器並非必要。您可以使用自定義的 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 命名空間下新增一些自定義屬性。

• 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 代表在應用程式路由器中渲染路由的過程。

屬性

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

擷取 [http.method] [http.url]

• next.span_type: AppRender.fetch

這個 span 代表在您的程式碼中執行的擷取請求。

屬性

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

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

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

• next.span_type: AppRouteRouteHandlers.runHandler。

這個 span 代表在應用程式路由器中執行 API 路由處理常式。

屬性

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

getServerSideProps [next.route]

• next.span_type: Render.getServerSideProps.

此跨度代表針對特定路由執行 getServerSideProps。

屬性

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

getStaticProps [next.route]

• next.span_type: Render.getStaticProps.

此跨度代表針對特定路由執行 getStaticProps。

屬性

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

render route (pages) [next.route]

• next.span_type: Render.renderDocument.

此跨度代表為特定路由渲染文件的過程。

屬性

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

generateMetadata [next.page]

• next.span_type: ResolveMetadata.generateMetadata.

此跨度代表為特定頁面產生中繼資料的過程（單一路由可以有多個此類跨度）。

屬性

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

解析頁面組件

• next.span_type: NextNodeServer.findPageComponents.

此跨度代表解析特定頁面的頁面組件的過程。

屬性

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

解析區段模組

• next.span_type: NextNodeServer.getLayoutOrPageModule.

此跨度代表載入佈局或頁面的程式碼模組。

屬性

• next.span_name
• next.span_type
• next.segment（區段）

start response

• next.span_type：NextNodeServer.startResponse。

這個長度為零的時間區段表示響應中第一個位元組發送的時間。