ClaudeDevs 称 Claude Platform 的 OpenTelemetry 追踪处于公开 Beta

发生了什么变化

ClaudeDevs 表示，span 遵循 OpenTelemetry 的 gen_ai 约定，默认携带耗时、状态、token 数量、模型和工具名等元数据。同一篇帖子说，把目的地切换到「full content」后，还会导出提示词、响应、工具输入和工具结果。

API 文档说，Claude API 会为每次模型请求和每次工具使用发出 span，范围是 Messages API 请求和 Managed Agents 会话。只要目的地已经存在，不必修改应用代码就能查看这些 span。默认情况下，一次请求或一次会话的 span 从自己的 trace 开始。这些 span 需要挂到应用 trace 下面时，API 会读取 W3C traceparent 头。如果该头里的 sampled 标志为关，API 不会发出该请求的 span，也不会发出它下面的 span。Claude Platform on AWS 尚不支持这个头。发往那里的请求，其 span 即使 sampled 标志为关，也总是从自己的 trace 开始。

SDK 文档描述的是另一条路径。SDK 在应用内部，为它发出的每次请求，以及 tool runner 执行的每次工具使用发出 span，再由应用自己的 OpenTelemetry 导出器送出。Beta 期间，SDK 选项和 span schema 可能破坏代码、查询或仪表板，其中包括重命名 span、属性、选项或环境变量。SDK 页面要求固定 SDK 版本。span 默认开启。

Console 目的地是 Metadata only 或 Full content。在 SDK 上，traces.content_mode 默认为 metadata_only。包含提示词和响应的 SDK 取值是 content，与 Console 目的地的 Full content 不是同一个标签。SDK 选项表列出每个 span 默认 0.75 MB，可用 traces.max_content_bytes 修改。这些页面点名的唯一 gen_ai 属性，是写在 gen_ai.conversation.id 上的可选会话 id，两种内容模式都会导出。SDK 页面说，不要在这个 id 里放入个人数据或秘密。如果 Full content 目的地仍然没有提示词或响应，API 文档指向一种可能：HIPAA、FERPA 或 K-12 限制。

同一次请求的 SDK span 和 API span 可能同名。这对 span 靠 span kind 或 service.name 区分。这与目的地把同一个 API span 收到两次是两回事。

• ClaudeDevs 公告
• Claude API 的 OpenTelemetry
• Claude SDK 的 OpenTelemetry

谁可以打开

添加或更改目的地，需要 Claude Console 组织中的 admin 角色。developer 角色可以查看目的地。在 Claude Platform on AWS 上，通过 AWS Console 登录。谁能在那里管理目的地，由 IAM 策略决定。

端点必须在 443 端口的 HTTPS URL 上接收基于 HTTP、使用 protobuf 的 OpenTelemetry Protocol（OTLP）。URL 使用主机名。文档说，自托管 collector 默认监听 4318 端口，因此要么在 443 上接收 HTTPS，要么在前面放负载均衡器或反向代理。凭据只放在头的值里。保存之后，Console 不再显示这些值。除非在同一主机上设置了 OTLP traces endpoint URL，否则 API 会加上 /v1/traces。对目的地执行 Test 会发送一个 anthropic.test span。端点返回 3xx 重定向、主机名解析到非公网 IP，或全部投递连续失败 24 小时时，API 会停用该目的地。原因修好之后，在目的地菜单里点 Enable 会恢复导出，导出大约在一分钟内重新开始。

工作区覆盖有三项设置。All 覆盖组织内的每个工作区，包括 Default Workspace 以及之后新建的工作区。All except 从这整个集合出发，去掉点名的工作区。Selected 只覆盖点名的工作区。API 会把 span 发给每一个已启用、且覆盖该请求或会话所在工作区的目的地。同时拥有 Workspace Admin 角色的 developer，可以在 Selected 目的地上添加或移除该工作区。Claude Platform on AWS 没有 Workspace Admin 角色。在那里，谁可以把工作区加到目的地或从目的地移除，由 IAM 策略决定。

管理员也可以用 Admin API 创建目的地。在 Claude Platform on AWS 上，这次调用发往 https://aws-external-anthropic.{region}.api.aws，并用 AWS 凭证签名。该调用的请求只能包含该账户在该 Region 中的工作区。

API 页面把这种服务端导出在 Claude API 和 Claude Platform on AWS 上标为 Beta。SDK 页面把追踪标为 Beta 的范围，是这两者再加上 Amazon Bedrock、Google Cloud 和 Microsoft Foundry。两页都说它适用于 Messages API 和 Claude Managed Agents。SDK span 由应用的导出器发送。API 发往目的地的 span，投递是 at least once，并且是 best effort。同一个 span 可能到达不止一次，这些副本用 trace ID 和 span ID 去除。投递前丢失的 span 不能再次发送。

投递之后，所选服务在 Anthropic 之外持有这些数据，并适用该服务自己的保留期限和访问控制。API 页面把 OpenTelemetry 标为 ZDR eligible，并加上对 covered models 的排除。该标签只适用于本身就是 ZDR eligible 的功能，例如 Messages API。同一则说明写道，Claude Managed Agents 不是 ZDR eligible。这些页面既没有定义 ZDR，也没有定义 covered models。

自托管的 Managed Agents 沙箱

在 Managed Agents 的自托管沙箱里，工具由沙箱运行，因此工具 span 来自 SDK，而不是 API。Python、TypeScript 和 Go SDK 中的 environment worker 会为它运行的每个工具、以及它发出的每个请求各发一个 span，并按每个工作项把它们归到一个 anthropic.environment.work span 下面。运行 worker 的进程需要配好 SDK 追踪，沙箱也必须能够到达可观测性平台或 collector。worker 送出工具结果时，该请求的 API span 会嵌在对应的 SDK span 之下。worker 发往 Claude Platform on AWS 的请求，其 API span 仍留在各自独立的 trace 里。