---
title: Claude API 的 OpenTelemetry
url: https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry
description: 使用來自 Claude SDK 和 Claude API 的 OpenTelemetry span，追蹤您的 Messages API 請求、工具使用和 Managed Agents 工作階段。
featureMetadata:
  topic:
    title: OpenTelemetry
    url: https://platform.claude.com/docs/en/manage-claude/opentelemetry
  status: beta
---

<Note>
  OpenTelemetry 匯出目前為測試版。它依據您與 Anthropic 之間的協議提供，包括[特定服務條款](https://www.anthropic.com/legal/service-specific-terms)中的測試版服務章節。
</Note>

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

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

## 開始使用

您可以設定 SDK 追蹤、API 追蹤，或同時設定兩者。同時設定兩者，即可在同一個追蹤中看到請求的 SDK span 和 API span，如[範例追蹤](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry#example-traces-and-how-to-read-them)所示。對於傳送至 Claude Platform on AWS 的請求，API span 則位於各自獨立的追蹤中。

<CardGroup cols={3}>
  <Card title="設定 SDK 追蹤" icon="code-brackets" href="https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/sdk" layout="horizontal">
    安裝 SDK 並註冊 tracer provider。
  </Card>

  <Card title="設定 API 追蹤" icon="cloud" href="https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/api" layout="horizontal">
    在 Claude Console 中新增目的地。
  </Card>

  <Card title="Span 參考" icon="book" href="https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans" layout="horizontal">
    查詢 span 及其屬性。
  </Card>
</CardGroup>

| 您獲得的內容                                                                                                           | SDK 追蹤                                                                        | API 追蹤                                                                                      | 兩者結合                                                                                        |
| ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [Messages API](https://platform.claude.com/docs/zh-TW/api/messages/create) 請求                                    | ✅                                                                             | ✅                                                                                           | ✅                                                                                           |
| [Sessions API](https://platform.claude.com/docs/zh-TW/managed-agents/sessions) 請求                                | ✅                                                                             | ✅                                                                                           | ✅                                                                                           |
| [Token 使用量](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry#count-tokens)                     | ✅                                                                             | ✅                                                                                           | ✅                                                                                           |
| 請求中的每次模型執行                                                                                                       | —                                                                             | ✅                                                                                           | ✅                                                                                           |
| [Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/overview) 回合                              | —                                                                             | ✅                                                                                           | ✅                                                                                           |
| 由 API 執行的[伺服器工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/server-tools)                  | —                                                                             | ✅                                                                                           | ✅                                                                                           |
| 由 [tool runner](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-runner) 執行的用戶端工具           | ✅                                                                             | —                                                                                           | ✅                                                                                           |
| [自行託管沙箱](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/sdk#trace-a-self-hosted-sandbox)中的工具 | ✅                                                                             | —                                                                                           | ✅                                                                                           |
| 其他 API 請求，例如上傳檔案                                                                                                 | ✅                                                                             | —                                                                                           | ✅                                                                                           |
| 設定方式                                                                                                             | [程式碼](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/sdk) | [Console](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/api)           | 兩者                                                                                          |
| 所需權限                                                                                                             | 無                                                                             | [管理員](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/api#what-you-need) | [管理員](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/api#what-you-need) |
| 涵蓋範圍                                                                                                             | 使用 SDK 的用戶端                                                                   | 任何用戶端                                                                                       | 任何用戶端                                                                                       |
| 雲端平台支援                                                                                                           | 任何                                                                            | Claude Platform<br />Claude Platform on AWS                                                 | Claude Platform<br />Claude Platform on AWS                                                 |

若要了解 Claude Code、Agent SDK 或 Cowork，請參閱 [Claude Code 監控](https://code.claude.com/docs/en/monitoring-usage)、[Agent SDK 可觀測性](https://code.claude.com/docs/en/agent-sdk/observability)或 [Cowork 活動監控](https://support.claude.com/en/articles/14477985-monitor-claude-cowork-activity-with-opentelemetry)。

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

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

<CardGroup cols={3}>
  <Card title="Arize AI" image="https://platform.claude.com/docs/images/partner-logos/arize.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/arize-dark.svg" imageOffsetLeft={2} href="https://arize.com/docs/ax/integrations/platforms/claude-managed-agents/claude-managed-agents-tracing">
    適用於 AI 的統一可觀測性與評估平台。
  </Card>

  <Card title="Braintrust" image="https://platform.claude.com/docs/images/partner-logos/braintrust.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/braintrust-dark.svg" imageHeight={25} imageOffsetLeft={1} href="https://www.braintrust.dev/docs/integrations/ai-providers/anthropic#export-opentelemetry-traces-from-the-claude-api">
    適用於代理的主動式可觀測性平台。
  </Card>

  <Card title="Databricks" image="https://platform.claude.com/docs/images/partner-logos/databricks.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/databricks-dark.svg" imageHeight={26} imageOffsetLeft={1} href="https://docs.databricks.com/aws/en/ai-gateway/unified-trace-table">
    用於可觀測性與評估的統一 AI 控制平面。
  </Card>

  <Card title="Datadog" image="https://platform.claude.com/docs/images/partner-logos/datadog.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/datadog-dark.svg" imageHeight={28} imageOffsetLeft={2} href="https://docs.datadoghq.com/llm_observability/instrument/otel_instrumentation/?tab=python#using-claude-managed-agents">
    AI 驅動的可觀測性與安全。
  </Card>

  <Card title="Grafana Cloud" image="https://platform.claude.com/docs/images/partner-logos/grafana.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/grafana-dark.svg" imageHeight={34} imageOffsetLeft={2} href="https://grafana.com/docs/grafana-cloud/observe-and-act/agent-observability/guides/send-claude-platform-traces/">
    全代管的開放式可觀測性平台。
  </Card>

  <Card title="Honeycomb" image="https://platform.claude.com/docs/images/partner-logos/honeycomb.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/honeycomb-dark.svg" imageHeight={36} imageOffsetLeft={4} href="https://docs.honeycomb.io/send-data/use-cases/claude-platform">
    適用於新型態軟體的可觀測性平台。
  </Card>

  <Card title="Langfuse" image="https://platform.claude.com/docs/images/partner-logos/langfuse.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/langfuse-dark.svg" imageHeight={26} imageOffsetLeft={1} href="https://langfuse.com/integrations/model-providers/claude-platform">
    開源的代理可觀測性與評估平台。
  </Card>

  <Card title="LangSmith" image="https://platform.claude.com/docs/images/partner-logos/langchain.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/langchain-dark.svg" imageHeight={29} href="https://docs.langchain.com/langsmith/trace-anthropic">
    LangSmith 代理工程平台。
  </Card>

  <Card title="New Relic" image="https://platform.claude.com/docs/images/partner-logos/new-relic.svg" imageHeight={27} imageOffsetLeft={1} href="https://docs.newrelic.com/docs/ai-monitoring/opentelemetry-ai-monitoring/#anthropic">
    智慧型可觀測性平台。
  </Card>

  <Card title="PostHog" image="https://platform.claude.com/docs/images/partner-logos/posthog.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/posthog-dark.svg" imageHeight={29} href="https://posthog.com/docs/ai-observability/installation/anthropic?tab=Claude+Platform&utm_source=anthropic&utm_campaign=anthropic-otel">
    打造成功產品的一站式平台。
  </Card>

  <Card title="Sentry" image="https://platform.claude.com/docs/images/partner-logos/sentry.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/sentry-dark.svg" imageHeight={25} href="https://sentry.io/cookbook/trace-claude-platform-with-opentelemetry/">
    為出錯的程式碼與行為異常的代理進行除錯。
  </Card>

  <Card title="Splunk" image="https://platform.claude.com/docs/images/partner-logos/splunk.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/splunk-dark.svg" imageHeight={27} imageOffsetLeft={1} href="https://agent-observability-docs.splunk.com/sdk-api/third-party-integrations/claude">
    觀測、評估並保護代理。
  </Card>
</CardGroup>

## 內容模式

每個目的地與每個 SDK 用戶端都有一個內容模式，用來設定 span 是否包含模型提示與回應。請在[新增目的地](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/api#add-a-destination)或[設定 SDK](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/sdk#configure-the-sdk) 時設定它。

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

使用 Full content 時，您還可以查看某次執行失敗或緩慢的原因、閱讀完整對話，以及從真實追蹤建立評估。在 [OpenTelemetry span 參考](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans)中，保存提示與回應的屬性會標記為 <Badge>Content</Badge>。

<Info>
  您的可觀測性平台會依其自身的存取與保留設定儲存這些內容，因此請確認這些設定符合您組織的要求。
</Info>

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

在[零資料保留](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention)下，您仍可使用 Full content。對於 Messages API 請求，API 僅將匯出的內容保留於記憶體中，直到將其傳送至目的地為止。[Claude Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/overview) 不符合零資料保留的資格，且使用 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` (typescript, java, php: `traces.maxContentBytes`; csharp: `Traces.MaxContentBytes`; go: `option.WithOpenTelemetryTracesMaxContentBytes()`)。在 Console 中，請在[新增目的地](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/api#add-a-destination)時將 **Content mode** 設為 **Full content**，然後在 **Advanced settings** 下設定 **Maximum content size in MB**。

## 範例追蹤及其解讀方式

### Messages API 請求

在[建立訊息](https://platform.claude.com/docs/zh-TW/api/messages/create)之請求的 API span 之下，API 會為每次模型請求新增一個 span，並為 API 執行的每次伺服器工具或 MCP 連接器工具使用新增一個工具 span。

在此範例中，您的應用程式呼叫 [tool runner](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-runner)，這是一個會執行您的工具並將其結果傳回給 Claude 的 SDK 輔助工具。tool runner 發出的每個請求都有一個來自 SDK 的用戶端 span 和一個來自 API 的伺服器 span。這些 span 依以下順序出現：

1. 您的應用程式啟動 `answer_question` span，並在其中呼叫 Messages tool runner（顯示為 [`anthropic.messages.tool_runner`](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-messages-tool-runner) span）。
2. tool runner 發出第一個請求（顯示為第一個 [`anthropic.messages.create`](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#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. 在第二個請求中，模型給出最終答案。

![Messages tool runner 追蹤範例：兩個請求，包含用戶端和伺服器 span、模型請求、web\_search 和 get\_weather](https://platform.claude.com/docs/images/opentelemetry-sdk-trace-shape.svg)

您應用程式中的 SDK 會發出 [`anthropic.messages.tool_runner`](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-messages-tool-runner) span、[`anthropic.custom_tool_use`](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use) span，以及每個請求的用戶端 span。若要取得這些 span，請[設定 SDK 追蹤](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/sdk)。

每個請求的 token 用量會出現在其多個 span 上。若要讓每個 token 只計算一次，請參閱[token 計算](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry#count-tokens)。

使用 [Full content](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry#choose-a-content-mode) 時，`anthropic.messages.create` 伺服器 span 會包含提示與回應。系統提示位於 `gen_ai.system_instructions`，請求的訊息位於 `gen_ai.input.messages`，回應則位於 `gen_ai.output.messages`。

關於每個 span 及其屬性，請參閱 [OpenTelemetry span 參考](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans)。

### Managed Agents 工作階段

工作階段中，每個 Sessions API 請求都有一個 span，每個代理回合都有一個回合 span。由某個請求啟動的回合，是該請求 span 的子項。一個回合包含每個模型請求以及 API 執行的每個工具的 span，但[工具 span 參考中列出的情況](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use)除外。它也包含每個結果評估的 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. 模型要求使用[自訂工具](https://platform.claude.com/docs/zh-TW/managed-agents/tools) `list_issues`，因此該回合以停止原因 `requires_action` 結束。
6. 工作階段工具執行器執行 `list_issues`（顯示為 `anthropic.custom_tool_use list_issues` span），並透過呼叫 `sessions.events.send` 傳送其結果。
7. 第二個回合以工具結果開始（顯示為最後一個 `anthropic.session.turn` span）。

![Managed Agents 工作階段的追蹤範例：您的 POST /chat span、工作階段工具執行器的事件串流和事件列表請求、傳送使用者訊息之請求的用戶端和伺服器 span、包含模型請求、一次 bash 工具使用和另一個執行緒上回合的回合、執行器執行 list\_issues、傳送工具結果之請求的用戶端和伺服器 span，以及第二個回合。](https://platform.claude.com/docs/images/opentelemetry-trace-shape.svg)

您應用程式中的 SDK 會發出 [`anthropic.custom_tool_use`](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use) span 以及每個請求的用戶端 span。若要取得這些 span，請[設定 SDK 追蹤](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/sdk)。

一個工作階段的 span 可能分布在多個 trace 中，例如當您從新的根 trace 傳送後續請求時。啟用[多代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration)時，一個工作階段也可能有多個執行緒。若要找到您需要的 span，請依 ID 將它們分組。

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

使用[完整內容](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry#choose-a-content-mode)時，您可以從工作階段的 span 讀取其內容。

* 若要讀取回合的內容，請使用其[回合 span](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-session-turn)。系統提示位於執行緒第一個回合 span 的 `gen_ai.system_instructions`，輸入位於 `gen_ai.input.messages`（您的訊息和工具結果、`system.message` 事件，以及來自其他執行緒的訊息），輸出則位於 `gen_ai.output.messages`（代理的訊息、工具使用和工具結果）。
* 若要查看工具使用的引數和結果，請讀取其[工具 span](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use)。引數位於 `gen_ai.tool.call.arguments`，結果位於 `anthropic.tool_result.content`。

關於每個 span 及其屬性，請參閱 [OpenTelemetry span 參考](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans)。

## 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：**&#x52A0;總 [`anthropic.messages.create`](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-messages-create) span。如果請求有[壓縮](https://platform.claude.com/docs/zh-TW/build-with-claude/compaction)，也請加上該 span 的 `anthropic.usage.compaction.input_tokens` 和 `anthropic.usage.compaction.output_tokens`，因為 `gen_ai.usage.*` 屬性不包含壓縮 token。如果請求是由[備援模型](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback)處理，其 span 只包含實際提供回應之模型的用量。
* **Messages API 請求的 API span：**&#x52A0;總 [`anthropic.messages.create`](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-messages-create) span 或其 [`anthropic.model_request`](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-model-request) span，但不要兩者都加總。如果請求有壓縮，也請加上其 [`anthropic.compaction`](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-compaction) span。不要再另外加上 `anthropic.messages.create` span 的 `anthropic.usage.compaction.*` 屬性，因為它們保存的是相同的 token。
* **Managed Agents 工作階段的 API span：**&#x52A0;總 `anthropic.model_request` 和 [`anthropic.session.outcome_evaluation`](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-session-outcome-evaluation) span。

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

`gen_ai.usage.input_tokens` 已包含從提示快取讀取和寫入的 token，因此請勿再將快取屬性加到其中。關於所有用量屬性，請參閱 [Token 用量](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#token-usage)。

<Note>
  匯出的 span 不保證是您 API 用量的完整紀錄。其傳送為[盡力而為](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/api#delivery-and-health)，因此 span 可能遺失。呼叫者也可以關閉請求的 [`traceparent` 標頭](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/api#connect-api-spans-to-your-own-traces)中的取樣旗標，藉此略過該請求的 span。若要追蹤每個 API 金鑰的用量（例如為了發現外洩的金鑰），請使用 [用量 API](https://platform.claude.com/docs/zh-TW/manage-claude/usage-cost-api#usage-api)，它也會計入沒有 span 的請求的用量。
</Note>