在 Claude SDK 中使用 OpenTelemetry

借助 OpenTelemetry，Claude SDK 可以为其发送的每个请求以及 工具运行器运行的每次工具使用发出一个 "span"（跨度）。您可以在您的可观测性平台中查看这些 span，它们嵌套在您自己的 "trace"（追踪）中。

SDK 在您的应用程序中发出 span。您应用程序的 OpenTelemetry 导出器会将它们发送到您的可观测性平台。

1. 安装 SDK

安装或升级到最新版本的 Claude SDK：

pip install --upgrade anthropic

pip install opentelemetry-sdk

2. 注册 tracer provider

"tracer provider"（追踪器提供程序）是创建 span 并将其传递给导出器的 OpenTelemetry 对象。SDK 会使用您的应用程序注册的 tracer provider，因此您的 SDK 调用保持不变。请在您想要追踪的第一次调用之前注册它。

以下示例注册了一个将每个 span 打印到控制台的 tracer provider，然后进行一次调用。在连接可观测性平台之前，您可以使用它来查看 span：

from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

# 注册一个 tracer provider，将每个 span 打印到控制台。
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)

client = Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content)

控制台会显示一个 anthropic.messages.create span。

3. 将 span 发送到您的可观测性平台

将控制台导出器替换为指向您可观测性平台的 OTLP 导出器。有关您所用语言的设置，请参阅 OpenTelemetry 文档中的 Python 导出器、TypeScript 导出器、.NET 导出器、Go 导出器、Java SDK 配置、PHP 导出器、或 Ruby 导出器。

4. 配置 SDK

使用以下选项来决定 span 中包含哪些内容以及将其发送到何处。您可以在代码中设置选项，也可以通过其名称下方列出的环境变量（如有）进行设置。

以下示例展示了如何使用每个选项：

# 使用指定的 tracer provider 并记录内容。
# 设置 open_telemetry 会覆盖所有 ANTHROPIC_OPEN_TELEMETRY* 环境变量。
client = Anthropic(
    open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}}
)

# 为单个客户端关闭 span。
quiet_client = Anthropic(open_telemetry=False)

# 通过 with_options() 设置会话 ID，该方法会返回客户端的副本。
# with_options() 会替换整个选项，因此请以 client.open_telemetry 为基础进行修改。
message = client.with_options(
    open_telemetry={**client.open_telemetry, "conversation_id": "conv_42"}
).messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

后续步骤

流追踪

流的 anthropic.messages.create span 会在您的代码读取完整个流或关闭流时结束，因此如果您提前停止读取某个流，请将其关闭。在内容模式下，只有当您使用 messages.stream() 读取流时，span 才会包含模型响应。

您在读取流时启动的 span 是 SDK span 的同级 span，而不是其子 span。要将它们与请求归为一组，请启动您自己的 span，将调用和读取循环都包含在内。

Managed Agents 自托管沙箱追踪

在 Managed Agents 自托管沙箱中，由您的沙箱运行工具，因此工具 span 来自 SDK 而非 API。Python、TypeScript 和 Go SDK 中的环境工作进程会为其运行的每个工具和发送的每个请求发出一个 span，并将它们归入每个工作项对应的一个 anthropic.environment.work span 之下。

要获取这些 span：

1. 在运行工作进程的进程中，按照步骤 1 到 4 设置 SDK 追踪。
2. 允许从沙箱到您的可观测性平台或 OpenTelemetry Collector 的网络流量。

当 worker 发送工具结果时，该请求的 API span 会嵌套在其 SDK span 之下。对于工作进程发送到 Claude Platform on AWS 的请求，API span 则位于它们各自的追踪中。

trace 上下文和 baggage

SDK 会在每个请求中使用您应用程序的传播器，通过 traceparent 等请求头将 trace 上下文发送给 API。如果该传播器还写入 baggage，SDK 也会发送您的 baggage。若想发送不含 baggage 的 trace 上下文，请只注册 W3C trace 上下文传播器。

若不想让 SDK 发送这些请求头（例如您的 HTTP 客户端插桩已经发送了它们），请关闭 SDK 的传播：

client = Anthropic(open_telemetry={"propagation": False})

SDK 调用 MCP 工具时，SDK 的工具 span 是当前 span。部分 MCP 客户端库会通过 _meta 将 trace 上下文发送到 MCP 服务器，因此读取它的服务器可以将自己的 span 添加到您的 trace 中，位于该工具 span 之下。2.0 及更高版本的 Python mcp 包和 C# ModelContextProtocol 包会这样做。TypeScript、Go、Java、Ruby 和 PHP 的 MCP SDK 不会自行这样做。

故障排除

Compatibility