搭配 Claude API 使用 OpenTelemetry

透過 OpenTelemetry，Claude API 可以為其執行的每個模型請求與每次工具使用發出一個「Span」（跨度）。您無需變更程式碼，即可在您的可觀測性平台中檢視這些 span。

API 會為您的 Messages API 請求與 Managed Agents 工作階段發出 span。若要接收它們，請在 Claude Console 中新增一個「destination」（目的地）。目的地會告訴 API 您的可觀測性平台的 OTLP 端點以及如何向其進行驗證。

您需要準備的項目

• 管理員角色：位於 Claude Console 組織中，用於新增和變更目的地。擁有開發者角色時，您可以檢視目的地。如果您的組織使用 Claude Platform on AWS，請依照登入中的說明，透過 AWS Console 登入 Console。
• 一個 OTLP/HTTP 端點，可在連接埠 443 的 HTTPS URL 上接受 protobuf 編碼。如果您自行執行 OpenTelemetry Collector，其 OTLP/HTTP 接收器預設監聽連接埠 4318。請將接收器設定為在連接埠 443 上接受 HTTPS，或在 Collector 前方放置負載平衡器或反向代理。
• 端點的憑證，例如 API 金鑰。

1. 新增目的地

1. 在 Console 中，開啟您組織的 OpenTelemetry 設定頁面，然後點擊 Add destination。

2. 設定目的地：

   欄位	輸入內容
   Provider	您的可觀測性平台；如果未列出，請選擇 Custom。如果您選擇已列出的平台，Console 會要求您提供其詳細資訊（例如 API 金鑰），而非 OTLP endpoint URL、Request headers 和 OTLP traces endpoint URL。
   Name	選填。例如「Acme 的可觀測性平台」。
   OTLP endpoint URL	您的可觀測性平台 OTLP/HTTP 端點的基礎 HTTPS URL，需使用主機名稱而非 IP 位址。它可以包含路徑前綴，例如 https://gateway.example.com/otlp。請勿加上 /v1/traces，因為 API 會自動加上它。如果您設定了 OTLP traces endpoint URL，API 則會改用該 URL。
   Request headers	API 隨每個請求傳送的標頭，例如您的可觀測性平台的 API 金鑰標頭。請只將憑證放在標頭值中。儲存後，Console 不會再次顯示這些值。
   Content mode	Metadata only 或 Full content。請參閱內容模式的差異。
   Workspaces	目的地接收其 span 的工作區：All、Selected 或 All except。請參閱為目的地選擇工作區。
   OTLP traces endpoint URL	選填，位於 Advanced settings 下。您的可觀測性平台追蹤端點的完整 URL，例如 https://gateway.example.com/custom/traces。當該平台在 OTLP endpoint URL 加上 /v1/traces 以外的 URL 接收追蹤時，請設定此項。它必須與 OTLP endpoint URL 使用相同的主機。
   Maximum content size in MB	選填，當內容模式為 Full content 時，位於 Advanced settings 下。API 在每個 span 中傳送的內容上限。Console 會根據您選擇的 Provider 填入此值。請依您的可觀測性平台可接受的大小進行變更。若將此欄位留空，則會傳送 API 所允許的最大內容量。請參閱內容限制。

3. 點擊 Add destination 以儲存。

4. 請在該目的地的 More actions 選單中點擊 Test。接著會顯示一則訊息，說明測試 span 已傳送至您的收集器，或傳送失敗的原因（請參閱傳送錯誤）。

5. 請確認您的可觀測性平台已收到 anthropic.test span。

Admin API 與 CLI

您也可以透過 Admin API 新增目的地，而不必使用 Console。請以管理員身分登入 CLI，或在 ANTHROPIC_API_KEY 中使用 Admin API 金鑰。在 Claude Platform on AWS 上，請改為將請求傳送至 https://aws-external-anthropic.{region}.api.aws，並依照發出請求中的說明，使用您的 AWS 憑證簽署。在此情況下，您的 IAM 政策決定誰可以管理目的地。請求只能包含您的 AWS 帳戶在該區域中的工作區。

client = anthropic.Anthropic()

destination = client.beta.organization.telemetry_destinations.create(
    endpoint_url="https://gateway.example.com/otlp",
    headers={"authorization": "Bearer YOUR_OBSERVABILITY_API_KEY"},
    traces={"content_mode": "metadata_only"},
    workspaces={"type": "all"},
)

print(destination.id)

建立請求接受 Console 中除 Provider 以外的設定，因此請自行輸入您可觀測性平台的端點 URL 與標頭。請以位元組為單位設定 traces.max_content_bytes，以符合您可觀測性平台可接受的大小（請參閱內容限制）。若要列出、變更或刪除目的地，或新增或移除單一工作區，請使用遙測目的地 API 的其他方法。

2. 為目的地選擇工作區

目的地會接收其涵蓋之工作區的 span。請在新增目的地時選擇這些工作區。在 Workspaces 中，選擇下列其中一項：

• All： 組織中的每個工作區，包括 Default Workspace 以及之後建立的工作區。
• Selected： 僅限您選擇的工作區。
• All except： 與 All 相同，但不包括您選擇的工作區。

若選擇 Selected 或 All except，請在選項下方出現的搜尋方塊中選擇工作區。若之後要變更目的地的工作區，請在 Workspace 篩選器顯示 All 時，於 OpenTelemetry 設定頁面上開啟該目的地的 More actions 選單。點擊 Edit，然後選擇另一個 Workspaces 選項，或在搜尋方塊中變更工作區。

如果您在組織中擁有開發者角色，並在某個工作區中擁有 Workspace Admin 角色，就可以將該工作區新增至 Selected 目的地，或將其從該目的地移除。請將 Workspace 篩選器設定為該工作區，然後開啟該目的地的 More actions 選單。在 Claude Platform on AWS 上，Console 沒有 Workspace Admin 角色。在該平台上，由您的 IAM 政策決定誰可以將工作區新增至目的地或將其從目的地移除。

API 會將 span 傳送至每個涵蓋請求或工作階段執行所在工作區的已啟用目的地。

3. 確認 span 已送達

1. 在 Console 中，選取該目的地所涵蓋的工作區，並在 playground 中傳送一個 Messages API 請求。您也可以從您的應用程式傳送 Messages API 請求，或在該工作區中啟動一個 Managed Agents 工作階段。若要啟動工作階段，您可以依照開始使用 Claude Managed Agents 中的步驟操作。
2. 在 Console 的 OpenTelemetry 設定頁面上，確認該目的地的 Delivery 欄顯示 Healthy。這可能需要約一分鐘。
3. 在您的可觀測性平台中，篩選 service.name = claude-platform 以找到該請求的 span。

如果該欄顯示 Failing，請將指標停留在其上以查看最後一次錯誤。若要找出可能的原因，請參閱傳送錯誤。

4. 將 API span 連接到您自己的追蹤

預設情況下，Messages API 請求或 Managed Agents 工作階段的 API span 位於各自獨立的追蹤中。請將它們連接到您應用程式的追蹤，使其巢狀於您自己的 span 之下。

API 會從 W3C traceparent 標頭讀取每個請求的追蹤上下文。如果標頭中的取樣旗標為關閉，API 就不會發出該請求的 span 或其下的 span。Claude Platform on AWS 尚不支援此標頭。您傳送至 Claude Platform on AWS 的請求，其 span 一律會開始各自獨立的追蹤，即使取樣旗標為關閉亦然。

from opentelemetry import trace

tracer = trace.get_tracer("my-service")

with tracer.start_as_current_span("summarize_issues"):
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Summarize the open issues"}],
            },
        ],
    )

import os
import httpx2
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator

headers = {
    "x-api-key": os.environ["ANTHROPIC_API_KEY"],
    "anthropic-version": "2023-06-01",
    "anthropic-beta": "managed-agents-2026-04-01",
    "content-type": "application/json",
}
# 將作用中 span 的追蹤上下文複製到請求標頭中。
TraceContextTextMapPropagator().inject(headers)

httpx2.post(
    f"https://api.anthropic.com/v1/sessions/{os.environ['SESSION_ID']}/events",
    headers=headers,
    json={
        "events": [
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Summarize the open issues"}],
            },
        ],
    },
)

Messages API 也會在您透過 MCP connector 連接您的 MCP 伺服器時，將追蹤傳遞給該伺服器，讓它可以將自己的 span 放在 API span 之下。API 傳送給您的 MCP 伺服器的每個請求與通知，都會在 params._meta 中帶有 W3C traceparent。在 tools/call 請求中，它指向該次工具使用的 anthropic.mcp_tool_use span。在其他訊息中，它指向 anthropic.messages.create span。對於 API 不追蹤的請求（例如 traceparent 標頭的取樣旗標為關閉的請求），API 不會傳送 traceparent。

後續步驟

傳送與健康狀態

以下規則適用於 API 傳送到您目的地的 span。

• 至少一次： 目的地可能會多次收到同一個 span。若要移除重複項目，請使用 trace ID 與 span ID。
• 盡力而為： span 可能在傳送前遺失。API 無法重新傳送遺失的 span。
• 壓縮： API 會以 gzip 壓縮每次傳送的第一個請求，並設定標頭 Content-Encoding: gzip。如果您的端點以 400 或 415 回應該請求，API 會立即以未壓縮的方式再次傳送相同的 span。
• 重試： 在逾時、連線、TLS 或 DNS 失敗，或收到 408、429 或 5xx 回應之後，API 會在稍後重試傳送，次數有限。API 不會重試其他失敗。
• 逾時： 對於每個請求，您的端點必須在 5 秒內完成 TLS 交握，並在 5 秒內傳送回應標頭。每次傳送（包括不使用壓縮的重新傳送）總計在 10 秒後逾時。
• User agent： 每個請求都帶有標頭 User-Agent: Claude-Platform。

Delivery 欄會顯示每個目的地的狀態。該狀態最多可能延遲一分鐘。

在以下情況下，API 會停用目的地：

• 端點傳送 3xx 重新導向。
• 端點的主機名稱解析為非公開的 IP 位址。
• 所有傳送持續失敗達 24 小時。

API 不會將 span 傳送至已停用的目的地。若要重新開始匯出，請修正原因。接著，在 OpenTelemetry 設定頁面上的 Workspace 篩選器顯示 All 時，在該目的地的 More actions 選單中點擊 Enable。匯出會在大約一分鐘內重新開始。

若要變更目的地，請在 Workspace 篩選器顯示 All 時開啟其 More actions 選單。然後點擊 Edit、Disable、Enable 或 Delete。如果您變更了 OTLP endpoint URL 的主機，請重新輸入標頭值。如果該目的地有 OTLP traces endpoint URL，請為其設定相同的新主機，或將其清除。

限制

疑難排解

傳遞錯誤

當傳遞失敗時，Delivery 欄會顯示 Failing。將指標停留在其上即可查看錯誤，然後找出可能的原因：

Compatibility