Next.js OpenTelemetry 可觀測性技能 (nextjs-otel)
一個模組化、可用於生產環境的工作流程，用於在 Next.js App Router 應用程式中配置、測試和驗證 OpenTelemetry 追蹤，標準化單一開關的使用，防止 @vercel/otel 初始化錯誤，並自動化追蹤驗證。
工作流程概覽
flowchart TD
A["1. 專案評估<br/>(App Router & package.json)"] --> B["2. 安裝相依套件<br/>(@vercel/otel & @opentelemetry/api)"]
B --> C["3. 部署 instrumentation.ts<br/>(registerOTel + onRequestError)"]
C --> D["4. 配置環境變數<br/>(.env.example & .env.local)"]
D --> E["5. 驗證與測試工具<br/>(模擬 Collector 與開關)"]
逐步執行 Runbook
請依序執行以下檢查清單，以配置和驗證 OpenTelemetry 可觀測性：
1. 專案探索與相依性檢查
- 檢查專案結構：確認
package.json中的 Next.js App Router 版本和套件管理器 (pnpm,bun,npm)。 - 定位 Instrumentation 根目錄：檢查專案使用的是根目錄的
instrumentation.ts還是src/instrumentation.ts。 - 檢視架構標準：參閱 architectural-standards.md 了解單一開關規範和執行邊界。
2. 相依性安裝
- 安裝核心遙測套件：
pnpm add @vercel/otel @opentelemetry/api
3. 部署 instrumentation.ts
- 建立 Instrumentation 檔案：將 instrumentation.ts.template 部署至根目錄或
src/。 - 套用真值保護：確保
register()在process.env.OTEL_SDK_DISABLED非嚴格等於"true"時將其刪除，以避免@vercel/otel的布林值評估錯誤。 - 串接錯誤追蹤：確保
onRequestError()能將next.error.digest、路由路徑和 HTTP 中繼資料擷取至活動跨度中。
4. 配置環境變數
- 更新環境範本：使用 env.otel.template 將 OpenTelemetry 配置注入
.env.example和.env.local。 - 設定服務名稱與協定：配置
OTEL_SERVICE_NAME、OTEL_EXPORTER_OTLP_ENDPOINT和OTEL_EXPORTER_OTLP_PROTOCOL=http/json。
5. 驗證與測試
- 啟動模擬 OTLP Collector：根據 verification-and-testing.md 在連接埠 4318 上啟動測試 collector：
node .agents/skills/nextjs-otel/scripts/mock_collector.js - 驗證活動追蹤 (
OTEL_SDK_DISABLED=false)：觸發測試請求 (curl http://localhost:3000/) 並驗證POST /v1/traces批次是否回傳 HTTP 200 OK。 - 驗證開關 (
OTEL_SDK_DISABLED=true)：確認 Next.js 伺服器日誌顯示[OTel] Instrumentation hook skipped且匯出 0 筆追蹤。 - 輸出驗證報告：產生 Markdown 摘要報告。
邊緣案例與已知 AI 陷阱
[!WARNING]
@vercel/otel字串真值錯誤：@vercel/otel評估!!process.env.OTEL_SDK_DISABLED。在 JavaScript 中，Boolean("false")等於true。若不將非'true'的process.env.OTEL_SDK_DISABLED刪除，設定OTEL_SDK_DISABLED=false會靜默地停用追蹤。- 次要自訂旗標：切勿在
OTEL_SDK_DISABLED之外引入OTEL_ENABLED。嚴格標準化使用OTEL_SDK_DISABLED。- 執行邊界違規：切勿將
instrumentation.ts或伺服器端 OpenTelemetry SDK 匯入至用戶端元件 ("use client")。- 鏈結指令：切勿使用鏈結指令 (
&&,||,;)。所有設定和測試指令應單獨執行。
輸出摘要結構
完成 OpenTelemetry 設定或驗證後，輸出結構化報告：
# OpenTelemetry 驗證報告
## 狀態摘要
- **OTel 狀態**：啟用 / 停用
- **服務名稱**：<設定的服務名稱>
- **目標端點**：<設定的端點>
- **匯出器協定**：http/json | http/protobuf
## 驗證結果
| 檢查項目 | 預期結果 | 實際結果 | 狀態 |
| :----------------------- | :----------------------- | :------------------- | :--- |
| 初始化掛鉤 | 已註冊 | 已註冊 | 通過 |
| 追蹤傳送 (啟用) | POST /v1/traces (200 OK) | X 批次已接收 | 通過 |
| 開關 (停用) | 已跳過，0 筆追蹤 | 已跳過，0 筆追蹤 | 通過 |
| 型別檢查 | 0 錯誤 | 0 錯誤 | 通過 |
參考指南與範本
- 架構標準參考 — 開關規範、真值錯誤機制和錯誤上下文。
- 驗證與測試 Runbook — 測試工具說明、curl 觸發和開關驗證。
- Instrumentation 範本 — 完整的
instrumentation.ts（含錯誤處理）。 - 環境配置範本 — 完整的
.env配置鍵。 - 模擬 Collector 腳本 — 輕量級 Node.js OTLP HTTP Collector 工具。