Claude API 支持 OpenTelemetry 追踪

图片：@ClaudeDevs (X)（视频截图）

摘要

Anthropic 于当地时间 10 月 14 日以公开测试版推出 Claude API 的 OpenTelemetry 追踪导出功能，支持 Messages API、Managed Agents 和 Claude SDK。
span 遵循 OpenTelemetry gen_ai 规范，默认只包含耗时、状态、令牌数、模型、工具名称等元数据；切换为完整内容模式后，还会导出提示词、回复以及工具输入和输出。
导出目标由管理员在 Claude 控制台中添加，每个组织最多 10 个；数据送达后由 Anthropic 以外的可观测性服务保存。

Now in public beta, Claude Platform can send OpenTelemetry traces from the Messages API, Claude Managed Agents, and the Claude SDKs

Anthropic 于当地时间 10 月 14 日以公开测试版推出了 Claude API 的 OpenTelemetry 追踪导出功能。Claude 开发者官方 X 账号 ClaudeDevs 表示，"Claude 平台可以把来自 Messages API、Claude Managed Agents 和 Claude SDK 的 OpenTelemetry 追踪发送到你的可观测性技术栈"。每一次模型请求、每一次工具使用都会生成名为 span 的记录单位，开发者无需修改代码，就能在已有的可观测性平台中查看。第一条帖子发布 3 小时后，浏览量达到约 31 万次。

导出内容分为两个层级。Anthropic 表示，"span 遵循 OpenTelemetry gen_ai 规范"，默认包含耗时、状态、令牌数、模型、工具名称等元数据。把导出目标切换为完整内容模式后，提示词、回复、工具输入和工具结果也会一并导出。根据平台文档，如果组织与 Anthropic 之间有 HIPAA、FERPA 或 K-12 数据处理限制，即使设置为完整内容，提示词和回复也可能被省略。

设置在 Claude 控制台中完成。在组织的 OpenTelemetry 设置页面添加导出目标，并填入可观测性平台的 OTLP 端点和认证请求头。添加或修改导出目标需要控制台组织的管理员角色，开发者角色只能查看。端点必须是通过 HTTPS 443 端口接收 protobuf 编码的 OTLP/HTTP；自行运行的 OpenTelemetry 收集器默认监听 4318 端口，因此需要改为接收 443 端口，或在前面加一个负载均衡器。每个导出目标可选择全部工作区、选定工作区或排除部分工作区。文档说明，设置完成后可在可观测性平台中筛选 service.name 为 claude-platform 的 span，控制台的投递状态变为正常大约需要 1 分钟。

API 一侧的追踪可以与开发者应用的追踪连接起来。API 从每个请求的 W3C traceparent 请求头读取追踪上下文，如果请求头中的采样标志关闭，就不会为该请求生成 span。它还会把 traceparent 传给通过 MCP 连接器接入的 MCP 服务器，使服务器能把自己的 span 放在 API span 之下。不过，Claude Platform on AWS 目前还不支持这个请求头，发往那里的请求的 span 总是各自开启新的追踪。

SDK 一侧直接使用应用注册的追踪器提供程序。根据文档，内容模式默认值为仅元数据，每个 span 的内容上限默认为 0.75MB。设置对话 ID 后，多次调用会归入同一个 gen_ai.conversation.id。关闭追踪上下文传播的选项可在 Python、TypeScript、Go、Java、Ruby 和 PHP SDK 中使用。SDK 追踪在 Claude API、Claude Platform on AWS、Amazon Bedrock、Google Cloud 和 Microsoft Foundry 上均以测试版提供支持。在自托管沙箱中运行 Managed Agents 时，工具 span 由 SDK 而非 API 生成，并按每个工作项归入一个 anthropic.environment.work span。

投递采用尽力而为的方式。文档写道，同一个 span 可能不止一次送达，因此需要用追踪 ID 和 span ID 去重，投递前丢失的 span 不会重新发送。端点必须在 5 秒内完成 TLS 握手、在 5 秒内返回响应头，每次投递总计 10 秒后超时。如果端点以重定向响应、解析到非公网 IP 地址，或连续 24 小时所有投递都失败，API 会停用该导出目标。每个组织最多可设置 10 个导出目标（含已停用的），每个目标最多可选 1000 个工作区，每个目标最多 20 个请求头。文档明确写道："送达后，数据由你选择的服务在 Anthropic 之外、按照该服务的保留和访问控制进行保存。"

METAL 查看的演示视频以故障响应智能体为例。告警触发后，智能体收集各服务的指标并撰写故障摘要；把错误状态的 span 按工具名称分组后发现，Query Metrics 工具在约三分之一的调用中超时，导致智能体在重试上多耗费了回合。视频中的开发者没有打开会话日志，约 30 秒就找到了原因，并把模型请求 span 的输入、输出和缓存令牌数按智能体分组，连重试的成本也一并确认。METAL 此前曾报道 Claude Managed Agents 推出动态工作流，这项新功能正是从外部观察这类更长智能体运行过程的窗口。