管理OpenTelemetry

Claude API 的 OpenTelemetry

Copy page



使用來自 Claude SDK 和 Claude API 的 OpenTelemetry span，追蹤您的 Messages API 請求、工具使用和 Managed Agents 工作階段。

Claude API 與 SDK 可以使用 OpenTelemetry 追蹤您的 Messages API 請求、工具使用以及 Managed Agents 工作階段。您可以在既有的可觀測性平台中檢視這些追蹤。您可以用它們來偵錯失敗或緩慢的請求、追蹤 token 花費與「latency」（延遲），並從真實流量建立評估。您也可以在應用程式自身的追蹤中看到每個請求，並連結到發出該請求的使用者或功能。

OpenTelemetry 是大多數可觀測性平台都支援的供應商中立標準。「Trace」（追蹤）是一個請求在您系統中的完整紀錄。「Span」（跨度）是追蹤中的一個步驟，例如一次模型請求或一次工具使用。API 與 SDK 使用 GenAI 語意慣例中的屬性，因此支援這些慣例的平台無需額外設定即可辨識這些 span。

開始使用

您可以設定 SDK 追蹤、API 追蹤，或同時設定兩者。同時設定兩者，即可在同一個追蹤中看到請求的 SDK span 和 API span，如範例追蹤所示。對於傳送至 Claude Platform on AWS 的請求，API span 則位於各自獨立的追蹤中。

若要了解 Claude Code、Agent SDK 或 Cowork，請參閱 Claude Code 監控、Agent SDK 可觀測性或 Cowork 活動監控。

將追蹤傳送至合作夥伴平台

將追蹤傳送至任何接受 OTLP 的可觀測性平台，包括下列合作夥伴：

內容模式

每個目的地與每個 SDK 用戶端都有一個內容模式，用來設定 span 是否包含模型提示與回應。請在新增目的地或設定 SDK 時設定它。

• Metadata only（SDK 中為 metadata_only）：預設值。span 包含識別碼、時間、狀態、token 數量，以及您選擇的文字，例如您的代理程式和工具的名稱與描述，以及您的 MCP 伺服器名稱。
• Full content（SDK 中為 content）：可見度最高。span 包含模型提示與回應，以及 Metadata only 中的所有內容。

使用 Full content 時，您還可以查看某次執行失敗或緩慢的原因、閱讀完整對話，以及從真實追蹤建立評估。在 OpenTelemetry span 參考中，保存提示與回應的屬性會標記為 Content。

如果您的組織與 Anthropic 之間有 HIPAA、FERPA 或 K-12 資料處理限制，無論目的地的內容模式為何，目的地都只會匯出中繼資料。SDK span 不受影響。

在零資料保留下，您仍可使用 Full content。對於 Messages API 請求，API 僅將匯出的內容保留於記憶體中，直到將其傳送至目的地為止。Claude Managed Agents 不符合零資料保留的資格，且使用 OpenTelemetry 時，其資料保留方式維持不變。

內容限制

使用 Full content 時，每個 span 預設最多可容納 0.75 MB 的內容。此限制可容納以英文文字填滿的 200k token 上下文視窗，同時維持在許多可觀測性平台和代理伺服器的 1 MB 請求限制以下。若您選擇合作夥伴平台作為 Provider，Console 會設定該平台所能接受的限制。

當內容超過限制時，SDK 或 API 會縮短內容，並將 anthropic.content.truncated 設為 true。請求 span 會先移除系統提示與最早的訊息，工具 span 則會從結果的結尾移除區塊。圖片和文件只會以其類型呈現。

在下列情況下請變更限制：

• 您的可觀測性平台可接受較大的酬載： 提高或移除限制，以完整保留較長的提示和回應。填滿 1M token 的上下文視窗約需 4 MB。
• 您的可觀測性平台或其前方的代理伺服器會拒絕大型請求： 降低限制。

在 SDK 中，請設定 traces.max_content_bytes。在 Console 中，請在新增目的地時將 Content mode 設為 Full content，然後在 Advanced settings 下設定 Maximum content size in MB。

範例追蹤及其解讀方式

Messages API 請求

在建立訊息之請求的 API span 之下，API 會為每次模型請求新增一個 span，並為 API 執行的每次伺服器工具或 MCP 連接器工具使用新增一個工具 span。

在此範例中，您的應用程式呼叫 tool runner，這是一個會執行您的工具並將其結果傳回給 Claude 的 SDK 輔助工具。tool runner 發出的每個請求都有一個來自 SDK 的用戶端 span 和一個來自 API 的伺服器 span。這些 span 依以下順序出現：

1. 您的應用程式啟動 answer_question span，並在其中呼叫 Messages tool runner（顯示為 anthropic.messages.tool_runner span）。
2. tool runner 發出第一個請求（顯示為第一個 anthropic.messages.create 用戶端 span 及其下的 span）。在此請求中，API 在兩次模型請求之間執行網頁搜尋工具。
3. 在第二次模型請求中，模型要求使用自訂的 get_weather 工具，因此第一個請求結束。
4. tool runner 執行 get_weather（顯示為 anthropic.custom_tool_use get_weather span）。
5. tool runner 帶著工具結果發出第二個請求（顯示為第二個 anthropic.messages.create 用戶端 span 及其下的 span）。
6. 在第二個請求中，模型給出最終答案。

您應用程式中的 SDK 會發出 anthropic.messages.tool_runner span、anthropic.custom_tool_use span，以及每個請求的用戶端 span。若要取得這些 span，請設定 SDK 追蹤。

每個請求的 token 用量會出現在其多個 span 上。若要讓每個 token 只計算一次，請參閱token 計算。

使用 Full content 時，anthropic.messages.create 伺服器 span 會包含提示與回應。系統提示位於 gen_ai.system_instructions，請求的訊息位於 gen_ai.input.messages，回應則位於 gen_ai.output.messages。

關於每個 span 及其屬性，請參閱 OpenTelemetry span 參考。

Managed Agents 工作階段

工作階段中，每個 Sessions API 請求都有一個 span，每個代理回合都有一個回合 span。由某個請求啟動的回合，是該請求 span 的子項。一個回合包含每個模型請求以及 API 執行的每個工具的 span，但工具 span 參考中列出的情況除外。它也包含每個結果評估的 span。

此範例追蹤一個聊天請求，在該請求中，您的應用程式向工作階段傳送訊息並執行自訂工具。此 trace 包含來自您的應用程式和 API 的 span，順序如下：

1. 您的應用程式收到來自使用者的 POST /chat 請求。
2. 您的應用程式啟動 SDK 的工作階段工具執行器，它會列出並串流工作階段的事件（顯示為 anthropic.sessions.events.stream 和 anthropic.sessions.events.list span）。
3. 您的應用程式透過呼叫 sessions.events.send 將使用者的訊息傳送至工作階段。
4. 一個回合開始，其中包含模型請求、一次 bash 工具使用，以及另一個執行緒上的回合（顯示為第一個 anthropic.session.turn span 及其下方的 span）。
5. 模型要求使用自訂工具 list_issues，因此該回合以停止原因 requires_action 結束。
6. 工作階段工具執行器執行 list_issues（顯示為 anthropic.custom_tool_use list_issues span），並透過呼叫 sessions.events.send 傳送其結果。
7. 第二個回合以工具結果開始（顯示為最後一個 anthropic.session.turn span）。

您應用程式中的 SDK 會發出 anthropic.custom_tool_use span 以及每個請求的用戶端 span。若要取得這些 span，請設定 SDK 追蹤。

一個工作階段的 span 可能分布在多個 trace 中，例如當您從新的根 trace 傳送後續請求時。啟用多代理時，一個工作階段也可能有多個執行緒。若要找到您需要的 span，請依 ID 將它們分組。

• 單一執行緒：依 gen_ai.conversation.id（其中保存工作階段執行緒 ID）將 span 分組。依開始時間排序，即可將該執行緒當作對話紀錄閱讀。
• 整個工作階段及其所有執行緒：跨 trace 依 anthropic.session.id 將 span 分組。

使用完整內容時，您可以從工作階段的 span 讀取其內容。

• 若要讀取回合的內容，請使用其回合 span。系統提示位於執行緒第一個回合 span 的 gen_ai.system_instructions，輸入位於 gen_ai.input.messages（您的訊息和工具結果、system.message 事件，以及來自其他執行緒的訊息），輸出則位於 gen_ai.output.messages（代理的訊息、工具使用和工具結果）。
• 若要查看工具使用的引數和結果，請讀取其工具 span。引數位於 gen_ai.tool.call.arguments，結果位於 anthropic.tool_result.content。

關於每個 span 及其屬性，請參閱 OpenTelemetry span 參考。

token 計算

若要讓每個 token 只計算一次，請針對每個請求只加總單一來源的 span。當 Messages API 請求同時具有 SDK span 和 API span 時，請加總其 API span。兩者都命名為 anthropic.messages.create，因此請依種類區分：SDK span 為 CLIENT，而其子項 API span 為 SERVER。

對於每個來源，請只加總下列 span，因為某些用量屬性會在 API span 的多個層級上重複出現：

• SDK span：加總 anthropic.messages.create span。如果請求有壓縮，也請加上該 span 的 anthropic.usage.compaction.input_tokens 和 anthropic.usage.compaction.output_tokens，因為 gen_ai.usage.* 屬性不包含壓縮 token。如果請求是由備援模型處理，其 span 只包含實際提供回應之模型的用量。
• Messages API 請求的 API span：加總 anthropic.messages.create span 或其 anthropic.model_request span，但不要兩者都加總。如果請求有壓縮，也請加上其 anthropic.compaction span。不要再另外加上 anthropic.messages.create span 的 anthropic.usage.compaction.* 屬性，因為它們保存的是相同的 token。
• Managed Agents 工作階段的 API span：加總 anthropic.model_request 和 anthropic.session.outcome_evaluation span。

span 可能會送達不只一次，例如當傳遞重試時。如果您的可觀測性平台不會移除重複項目，請依 trace ID 和 span ID 讓每個 span 只計算一次。

gen_ai.usage.input_tokens 已包含從提示快取讀取和寫入的 token，因此請勿再將快取屬性加到其中。關於所有用量屬性，請參閱 Token 用量。