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 與邊緣運行環境不相容，因此您需要確保僅在 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

您需要一個具有相容後端的 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 exporter 搭配 @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.ts、layout.ts、loading.ts 等）。
  • 它僅在與 next.route 搭配使用時才能用作唯一識別碼，因為 /layout 可用於識別 /(groupA)/layout.ts 和 /(groupB)/layout.ts。

[http.method] [next.route]

• next.span_type：BaseServer.handleRequest

此追蹤範圍代表每個傳入 Next.js 應用程式的請求的根追蹤範圍。它追蹤請求的 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。

此追蹤範圍代表在應用程式路由器中渲染路由的過程。

屬性

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

fetch [http.method] [http.url]

• next.span_type：AppRender.fetch

此追蹤範圍代表在您的程式碼中執行的提取請求。

屬性

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

您可以透過在您的環境中設定 NEXT_OTEL_FETCH_DISABLED=1 來關閉此追蹤範圍。當您想使用自訂的提取檢測程式庫時，這會很有用。

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

• next.span_type：AppRouteRouteHandlers.runHandler。

此追蹤範圍代表在應用程式路由器中執行 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

渲染路由 (頁面) [next.route]

• next.span_type：Render.renderDocument

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

屬性

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

產生 Metadata [next.page]

• next.span_type：ResolveMetadata.generateMetadata

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

屬性

• 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（區段）

開始回應上一頁

檢測工具

下一頁

第三方函式庫

這有幫助嗎？

支援。

傳送