Workers RPC 追蹤怎麼看？用 traces 找跨 Worker 與 Durable Objects 延遲

2026-09-18

伺服器

Cloudflare

/

/

/

/

Worker 透過 JavaScript RPC 呼叫另一個 Worker 或 Durable Object 時，單看 caller log 很難知道時間花在哪裡：是建立 session、執行 method、進入 callee，還是 callee callback 回到另一個 Worker？Cloudflare 在 2026 年 9 月 17 日更新 Workers traces，讓追蹤可以跨 Worker boundary 和 Durable Objects 看見 RPC session、invocation 與 method call。

直接答案是：先在 Wrangler 設定開啟 observability.traces.enabled，部署後用一個可重現的 RPC 請求產生 trace，再依 root span、RPC session、individual call 和 callee invocation 的順序閱讀。這項自動 instrumentation 不需要改應用程式碼或另裝 observability SDK，但它仍不是取代業務 log、錯誤追蹤或負載指標的萬用方案。

本文依 Cloudflare Changelog 與 Spans and attributes 文件整理，沒有在帳號部署或查詢 dashboard。

這次更新補上哪一段觀測#

更新前，trace 會在 caller 的 RPC boundary 停下來；現在 dashboard 可以把 caller-side session 與 method calls，連同 callee invocation、nested calls 和 callbacks 放在同一條關聯裡：

Span	所在位置	看什麼
RPC session	caller side	一個 RPC session 的生命週期，以及重用該 session 的呼叫
RPC call	caller 或 callee side	單一 method call 或 property access
RPC invocation	callee side	目標 Worker 或 Durable Object 中的一次 RPC invocation
Root span	觸發請求的 Worker 或 handler	整體 outcome、CPU time、wall time 與 request 關聯

文件指出，caller 和 callee 的 span 會使用各自 Worker 或 Durable Object 的 execution color；顏色切換能幫你辨認執行邊界。這不是把所有程式碼函式都自動變成自訂 span，而是把 Cloudflare 已支援的 runtime 與 RPC 邊界呈現得更完整。

在 Wrangler 開啟 traces#

JSON 設定可以加入：

1
{
2
  "$schema": "./node_modules/wrangler/config-schema.json",
3
  "observability": {
4
    "traces": {
5
      "enabled": true
6
    }
7
  }
8
}

TOML 寫法則是：

1
[observability.traces]
2
enabled = true

設定要部署到實際產生 RPC 流量的 Worker。只在本機檔案改好，或只對 caller 開啟卻沒有部署，dashboard 都可能看不到你預期的 trace。Cloudflare 的更新說明表示，這項 instrumentation 不需要你改 handler 或安裝 SDK；若需要應用程式業務欄位，仍要另外保留結構化 log 或自訂觀測方案。

Dashboard 的閱讀順序#

不要一打開 trace 就先盯著最長的 method 名稱。用下面順序比較容易把延遲定位到責任邊界：

先看 root span：確認 trigger、Worker version、region、cloudflare.outcome、CPU time 和 wall time，先排除這其實不是你以為的 deployment。
找 RPC session：看 session 的起訖範圍與底下是否重用了多個呼叫。長 session 不必然是問題，但能提示你不要把每個 method 當成獨立連線。
對照 RPC call：看 jsrpc.method、jsrpc.operation 和 jsrpc.target_kind，區分 method call 與 property access，以及實際目標類型。
沿著顏色邊界到 invocation：進入 callee 後，分辨時間是在目標 Worker／Durable Object 的 invocation、nested call，還是 callback 回程。
最後才看應用程式 log：用 invocation id、version、Ray ID 或你自己的 request id 對照錯誤和業務事件，不要只靠時間戳猜兩次請求是不是同一筆。

RPC call 的 callee-side span 會提供 jsrpc.caller_span_id，可用來把目標端的 span 對回 caller-side call。當兩個事件時間非常接近時，文件也提供 cloudflare.invocation.sequence.number 協助區分先後。

用 traces 分辨四種常見延遲#

觀察結果	比較合理的下一步
root wall time 長，但 RPC session 很短	先查 caller 其他 fetch、binding 或等待，不要把問題全推給 RPC
session 內有很多重複的 call spans	檢查 client 是否反覆取得 property 或重複呼叫同一個 method
caller call 很快，callee invocation 很長	查目標 Worker／Durable Object 的 CPU、資料庫、外部 fetch 與 application log
callee 完成後 callback 又進入另一個 boundary	沿著 nested／callback spans 逐段比對，不要只看第一個 call 的 duration

Trace 能讓執行邊界可見，但不會自動告訴你「這個 method 為什麼在產品上被呼叫」。如果要回答租戶、訂單、工作 id 或業務動作，仍要在不洩漏敏感資料的前提下建立可關聯的 application log。

沒看到 RPC trace 時先查什麼#

啟用設定後沒有資料，不要立刻改 RPC 實作。先依順序排查：

確認 observability.traces 的檔案格式和縮排，並檢查真正部署的 Worker version。
確認請求真的走 JavaScript RPC，而不是普通 HTTP、service binding 的另一種介面或本機 mock。
用單一、可重複的 caller → callee 請求產生流量，再從 root trace 往下找；不要用同時大量請求的 production 峰值當第一個案例。
檢查 dashboard 的時間範圍、Worker 名稱、region 和 deployment version 是否選對。
若只有部分 span，對照 Cloudflare 支援的 spans 與 attributes 和 Traces known limitations，不要把未列出的 runtime 行為當成一定會出現。

如果要在 CI 重現跨 Worker 情境，可以參考 Workers integration test harness 建立接近 production build 的測試；但本機測試通過，不代表遠端 dashboard 的收集、版本與流量條件已經驗證。