Vercel 在 2026 年 11 月 13 日宣布,Daemons 可以把 OpenTelemetry traces 傳到 Vercel Tracing。平台會在每個 daemon 提供接收 OTLP/HTTP traces 的 Unix socket,並透過 VERCEL_OTEL_SOCKET_PATH 告知路徑;Node.js 專案把 @vercel/otel 升到 2.3.0 以上並使用預設設定,就能自動偵測 socket,把 worker spans 與網站其他 traces 放在同一個專案中查詢。
這解決的是長時間背景程序原本難以和前台 request 串起來的觀測缺口,但不是升級套件後就自動得到完整因果鏈。若 queue message 沒有傳遞 trace context、span 名稱與 attributes 沒有規範,或錯誤只寫 log 沒有記錄 span status,畫面上仍只會出現彼此斷裂的片段。導入重點應放在「一筆業務工作能否從入口一路追到 daemon」,而不是單純增加 span 數量。
哪些背景工作最需要這次更新
Daemons 適合長時間執行、持續從 queue、資料庫或第三方來源取工作的程序,例如圖片轉檔、通知派送、資料同步、搜尋索引與代理任務。這些流程常跨過 HTTP request 的生命週期:前台已回覆成功,真正處理卻可能幾分鐘後才失敗。只有 request log 時,營運人員很難回答某張訂單是否排入 queue、由哪個 worker 取得、重試幾次,以及卡在哪個外部 API。
Tracing 可把 enqueue、dequeue、處理、資料庫與外部呼叫表示成同一條 trace 或可連結的 spans,適合找出慢點與錯誤邊界。Metrics 仍負責整體量、延遲分布、queue depth 與告警;logs 適合保留離散事件與除錯內容;traces 則用於追蹤單次工作路徑。三者互補,不能因 traces 可搜尋就取消 queue backlog、dead-letter 或程序存活監控。
升級前先確認初始化與執行模式
官方範例要求在 worker 開始工作前呼叫 registerOTel。因此初始化檔要早於 queue consumer、資料庫 client 與應用模組載入,否則部分自動 instrumentation 可能錯過建立時機。先把 @vercel/otel 固定到已驗證的 2.3.0 以上版本,更新 lockfile,在 staging 檢查 VERCEL_OTEL_SOCKET_PATH 存在,再確認 spans 能出現在正確 project 與 service name。
不要在程式中自行猜 Unix socket 路徑,也不要把 production 的 socket 設定複製到本機。程式應容忍非 Vercel 環境沒有該變數,依環境選擇本機 collector、測試 exporter 或關閉輸出。若已經自訂 OpenTelemetry exporter 或 SDK,需先查清楚預設設定是否會建立第二個 provider、重複輸出或覆蓋 sampling;不要只在原設定旁再呼叫一次初始化。
service name 應穩定、可區分角色,例如 billing-worker 或 image-worker,不要帶 deployment ID、pod ID 或 task ID 造成高基數。deployment、environment 與版本適合當 resource attributes;order ID、job ID 等業務識別可在確有調查需求且符合資料政策時加入,但要限制基數與敏感性。
跨 queue 的 context 要自己設計
HTTP 入口建立 trace 後,producer 應把標準 trace context 放入 message metadata;consumer 取出後建立 consumer span,再在其下建立處理與外部呼叫 spans。若 queue 可能延遲很久或一則訊息會觸發多個下游工作,可依 OpenTelemetry 語意選擇 parent-child 或 span links,並在團隊規範中固定做法。
不是所有 retry 都應偽裝成同一個連續函式呼叫。每次 attempt 應記錄 attempt number、queue name、message type、結果與可控的 error category;原始 job ID 用於關聯,避免把完整 payload 放進 attribute。dead-letter、取消與超時也要有明確 span status,否則只有成功 attempt 出現在 trace 時,會誤以為工作從未失敗。
外部 API、資料庫與快取可使用自動 instrumentation,但業務階段仍需要少量手動 spans,例如「保留庫存」「建立付款」「寄出通知」。名稱應代表穩定操作,不要直接使用 URL、SQL、email 或客戶名稱。這讓不同 deployment 的 traces 可以比較,也降低敏感資料與高基數造成的費用風險。
Sampling、資料保護與成本不能最後才看
高流量 daemon 若記錄每個內部步驟,trace volume 可能快速增加。先定義最低必要 spans,再依環境與工作類型設定 sampling。錯誤、超時與高價值交易要優先保留,正常且高頻的健康工作可降低比例。採樣規則必須用實際帳戶方案與 Vercel 最新文件查核,不能假設所有 traces 都會永久保存或免費查詢。
span attributes 與 events 不應包含 access token、cookie、完整 request body、付款資料、個資或未遮罩的錯誤物件。OpenTelemetry context 可以跨服務傳遞,但業務 payload 不應因此被複製到 observability 系統。建立 attribute allowlist、字串長度限制與錯誤清洗,並用測試資料檢查 dashboard 與 CLI 輸出。
官方公告也指出 Vercel CLI 能依 project 與 service name 搜尋 traces 並回傳 JSON,這很適合事故調查或內部工具,但 CLI token 同樣需要最小權限。不要把能查 production traces 的個人 token 放進公開 CI log,也不要讓自動化把整份 trace JSON 貼到外部工單;應只摘要必要的 trace ID、錯誤類別與連結。
從 staging 到 production 的驗收清單
先建立一個可控制的測試 job,包含一次資料庫查詢、一次外部呼叫、成功與故意失敗分支。從 HTTP 或排程入口送出後,確認 trace 能看到 enqueue、queue delay、daemon receive、各業務階段與最終結果;trace ID 應能和應用 log、job ID 對上。接著測試 retry、dead-letter、程序重啟與 graceful shutdown,確認未送出的 spans 不會大量遺失,也不會因 exporter 問題阻塞業務處理。
第二步用 production 相近流量壓測,比較加入 instrumentation 前後的 CPU、記憶體、處理延遲與錯誤率。沒有量測就不要宣稱負擔可忽略。第三步先讓單一低風險 daemon 上線,建立 queue depth、失敗率與 p95 處理時間告警,再逐步擴到其他 worker。回滾要能只停用 exporter 或退回套件版本,不應要求改掉業務 queue。
導入完成後,用三個問題驗收:客服提供 job ID 時能否在合理時間找到完整路徑;告警發生時能否分辨 queue 等待、程式處理或外部服務變慢;部署新版本後能否依版本比較錯誤與延遲。如果做不到,應改善 context 與 span schema,而不是繼續增加更多未命名 spans。
Vercel Daemons 接入 Tracing 的實際價值,是讓背景工作不再成為前台 request 之後的黑盒。適合採用的團隊應先有明確 queue 與 job 狀態,再用 OpenTelemetry補上跨服務關聯;若目前連 retry、dead-letter 與業務 ID 都沒有,先整理工作流程,會比直接追求漂亮的 trace 圖更重要。