摘要： Anthropic 在 Claude API 與 SDK 中加入 OpenTelemetry 匯出功能（目前為 beta），能追蹤 Messages API 請求、工具使用與 Managed Agents 回合。這些 span 遵循 GenAI 語意慣例，可以直接送進你已經在用的觀測平台。對 builder 來說，除錯慢請求、追 token 成本、從真實流量建立 eval，終於不用另外搭一套監控了。
為什麼這件事值得你花半小時
LLM 應用最難排查的從來不是「有沒有回應」，而是「為什麼這次慢了三秒」和「這個月的 token 預算到底花在哪」。過去要回答這些問題，往往得靠各家平台的專屬 logging 或自己埋點。這次 Anthropic 直接走 OpenTelemetry 這個供應商中立的標準，讓 trace 進入你既有的觀測工具鏈。
根據 Anthropic 的官方文件，一個 trace 是請求在系統中的完整紀錄，一個 span 是其中一步（例如一次模型請求或一次工具呼叫）。因為採用 GenAI 語意慣例，支援該慣例的平台不用額外設定就能辨識這些 span。
SDK tracing 和 API tracing 該選哪個
兩者可以分開用，也可以一起開，覆蓋範圍不一樣：
- SDK tracing：在程式碼裡安裝 SDK 並註冊 tracer provider，涵蓋 client 端的 span，例如 tool runner 執行自訂工具、上傳檔案等其他 API 請求。不需要特殊權限。
- API tracing：在 Claude Console 加一個目的地即可，涵蓋任何 client 發出的請求，而且能看到請求內部的每一次模型呼叫、server tools 和 Managed Agents 回合。需要 Admin 權限。
兩者一起開的好處是同一個請求的 client 與 server span 會出現在同一條 trace 裡，方便看見「我的程式送出請求」到「API 內部跑了 web search、呼叫我的 get_weather 工具」的完整過程。注意一個限制：在 Claude Platform on AWS 上，API spans 會在獨立的 trace 裡。
Content mode 是你真正要做的決定
預設是 Metadata only：span 只含識別碼、時間、狀態、token 數，以及你主動選擇的文字（例如 agent 和工具的名稱）。要看到完整的 prompt 和回應，得切到 Full content——這是從真實流量建立 eval 的前提，但也代表對話內容會存進你的觀測平台，受該平台自己的存取與保留政策管轄。
有幾個務實的細節：
- 有 HIPAA、FERPA 或 K-12 資料限制的組織，目的地一律只匯出 metadata，不受 content mode 影響。
- Full content 模式下每個 span 預設上限 0.75 MB（大約容納 200k token 的英文文本），超過會截斷並標記
anthropic.content.truncated；1M token 的 context 約需 4 MB，可自行調整traces.max_content_bytes。 - 使用 zero data retention 的話仍可用 Full content，內容只暫存在記憶體直到送達目的地。
和既有工作流接起來
只要平台接受 OTLP，就能收這些 trace，文件列出的合作夥伴包括 LangSmith 等多家觀測與評估平台。這和之前談過的 LangSmith 用自然語言查詢 agent trace 的做法 是同一個方向：trace 資料不只是除錯紀錄，而是回答產品問題的原材料——使用者卡在哪、哪類請求特別慢、哪些對話值得拿來做 eval。
實務上的起步順序很簡單：先在 Console 開 API tracing 拿到全貌（需要 Admin），再視需要補上 SDK tracing 看 client 端工具。等確認平台儲存與保留政策符合組織要求，再考慮開 Full content。beta 狀態下的服務條款適用，正式環境依賴前先確認你的合約涵蓋範圍。
參考來源
在 X 上查看原貼文