Claude OpenTelemetry 导出 beta：接入步骤、内容模式与投递限制

先选择 API 端追踪、SDK 端追踪，或两者组合

Anthropic 在 2026 年 10 月 14 日的开发者更新中宣布 OpenTelemetry export beta。span 是链路中一次模型请求或工具操作的追踪记录。

当前文档支持追踪 Messages API 请求与 Claude Managed Agents 会话：SDK 端提供客户端视角，API 端还能提供服务端模型请求和工具使用等 span。API 端接入通过 Console 配置 destination，无需为这些服务端 span 修改应用代码。

若希望把客户端与服务端操作连成一条链路，可以组合两类追踪。公告列出 Python、TypeScript、C#、Go、Java、PHP、Ruby SDK，但这组来源没有给出最低版本；实际 SDK 安装和埋点应核对对应指南。Claude Code、Agent SDK 和 Cowork 另有监控文档，不能把这里的 destination 当成它们的统一开关。

配置前确认权限、接收协议和工作区范围

第一步，确认自己具有 Claude Console 组织的 admin 角色，才可新增和修改 destination；developer 角色可以查看。

接收端必须支持 OTLP/HTTP 的 protobuf 编码，使用 HTTPS 443 与主机名，不能填写 IP 地址。自建 Collector 默认监听的 4318 端口，不能直接当成这里要求的公网 HTTPS 入口。

第二步，在 OpenTelemetry settings 中选择 Add destination，再选择 Provider。已列出的平台会要求它需要的详情，例如 API key；选择 Custom 时，填写接收地址和认证请求头。

基础 OTLP endpoint URL 不要再加 /v1/traces，API 会自动追加；Advanced settings 的完整 traces URL 必须与基础地址同主机。凭据只放在请求头的值里，保存后不再显示。

第三步，选择 Content mode 和 Workspaces。假设只想接入一个试用工作区，应选择 Selected 并指定它；All 会包含组织中的所有工作区及以后新建的工作区，All except 则排除指定项。这是范围选择示例。请求所在工作区若被多个已启用 destination 覆盖，API 会向这些 destination 分别发送 span。

先检查测试 span，再观察实际业务请求

保存后，官方流程是在 destination 的 More actions 中点击 Test，并到接收平台确认 anthropic.test span 是否到达。测试失败时先看提示的投递错误，区分认证、路径、DNS、TLS 与超时问题，不必先改动模型请求。

当已授权的 Messages API 请求或 Managed Agents 会话在覆盖的工作区运行后，可查看 Console 的 Delivery 列，并在接收端按 service.name=claude-platform 查找 API span。状态和工作区覆盖的生效可能延迟约一分钟。Healthy 表示最近一次投递成功，不代表历史 span 全部齐全。

如果没有数据，先确认 destination 已启用且覆盖正确工作区，再检查接收地址与认证。官方将 401/403 指向认证请求头问题，404 指向 endpoint 路径问题；这些是排查方向，不能仅凭一个状态码断定所有请求失败的原因。

内容模式决定导出什么，保留规则由接收端另行管理

Metadata only 默认导出标识符、时间、状态、token 数量，以及你选择填写的文本，例如 agent、工具的名称和描述、MCP server 名称。因此，元数据模式不等于没有任何需要保护的文本。Full content 在此基础上增加模型提示与回答，接收平台会按自己的访问控制与数据保留设置存储这些内容。

Full content 的默认单 span 内容上限为 0.75 MB，选择特定 Provider 时 Console 也可能采用该平台可接受的上限。超过限制会截短内容并设置 anthropic.content.truncated=true；请求 span 先丢弃系统提示和最早的消息，图片与文档仅以类型呈现。不能把 trace 当成保证完整的会话备份。

组织若与 Anthropic 有 HIPAA、FERPA 或 K-12 数据处理限制，destination 无论选择什么模式都只导出元数据；此规则不影响 SDK span。

零数据保留条件下，符合资格的 Messages API 仍可使用 Full content，API 将待导出内容保留在内存直到投递；Managed Agents 本身不符合零数据保留资格。接收端的数据保留责任仍需单独确认。

串联应用 trace 时，注意 AWS 与采样差异

默认情况下，API span 自成 trace。若要接到应用自己的链路，官方文档使用 W3C traceparent 传递上下文；将 SDK 追踪和 API 追踪发往同一可观测性平台，才能在那里组合查看。在支持该 header 的路径中，sampled 标记关闭时，API 不生成该请求及其子 span。

Claude Platform on AWS 当前不支持这个 header，其 API span 总是新建 trace，即使 sampled 标记关闭也如此。

兼容性表列出的 API 追踪平台是 Claude API 与 Claude Platform on AWS，均为 beta；这不构成对其他云平台、所有地区或所有账户资格的承诺。这几份来源也未列出专项费用，不能据此认定服务或接收平台免费。

投递可重试也可能丢失，用量统计另走完整渠道

投递采用尽力而为方式，可能重复，也可能在送达前丢失；已丢失的 span 不能重新发送。接收端可按 trace ID 与 span ID 去重。API 只对特定超时、连接故障和 408、429、5xx 等情况有限重试；接收端返回重定向、主机名解析到非公开地址，或持续 24 小时全部投递失败，会使 destination 被禁用，修复后需重新启用。

因此，不应靠 span 是否出现判断一次请求是否计费，或把 trace 总量当成完整用量账本。官方建议通过 Usage API 跟踪各 API key 的用量。追踪适合定位失败、慢请求和工具调用过程；beta 条款、实际 SDK 兼容性与接收平台的数据管理仍应按自己的接入范围核对。