Claude OpenTelemetry怎么开？Console添加Destination、SDK追踪与Managed Agents链路教程（Public Beta）

依据Claude官方公告与platform.claude.com、code.claude.com文档整理；beta期间字段可能变更。核查2026-10-15（新加坡时间）。

主题标签：Claude OpenTelemetry、Claude链路追踪、Claude Managed Agents追踪、Claude OTel、Claude可观测性

Claude的OpenTelemetry怎么开？两条路，可以只开一条，也可以两条都开：API追踪在Claude Console的OpenTelemetry设置页添加一个destination（需要组织admin权限），之后Messages API请求和Managed Agents会话会自动把span推到你的观测平台；SDK追踪只要在代码里先注册OpenTelemetry的tracer provider，Claude SDK就会自动发span，不用改调用代码。这个功能2026-10-14以public beta形式上线，默认只发元数据，不发提示词原文。

先弄清楚：API追踪和SDK追踪看到的东西不一样

很多人开了一边就以为看全了。官方文档有一张对照表，我们按“排查问题时最常想看的东西”重新排了一下：

想看什么	SDK追踪	API追踪
每次Messages / Sessions请求、token用量	有	有
一次请求内部的每轮模型调用	无	有
Managed Agents的每个turn	无	有
服务端工具（如web search、MCP connector工具）	无	有
你自己的客户端工具（tool runner跑的）	有	无
自托管沙箱里的工具	有	无
上传文件等其他API请求	有	无
怎么开 / 权限	写代码，无需权限	Console配置，需admin

结论很简单：做Agent的团队最好两边都开，这样客户端span和服务端span能拼进同一条trace。走Claude Platform on AWS的请求例外，API span会单独成trace。

API追踪：在Console加destination（约10分钟）

准备一个OTLP/HTTP端点：必须是HTTPS、443端口、protobuf编码，且用域名不用IP。自建OpenTelemetry Collector默认监听4318，需要改成443或在前面挂反向代理。
Console进入组织的OpenTelemetry设置页，点Add destination。
Provider选你的平台（列表里有Langfuse、Datadog、Grafana Cloud、Sentry、Honeycomb等），没有就选Custom。
填OTLP endpoint URL，不要自己加/v1/traces，API会补；鉴权放在Request headers里，保存后Console不再显示明文。
选Content mode（下一节细说）和Workspaces：All、Selected或All except。
保存后在More actions里点Test，去平台里找名为anthropic.test的span。
再从Playground发一条Messages请求，约一分钟后Delivery列应显示Healthy；平台里按service.name = claude-platform过滤。

不想点界面的话，也可以用Admin API或ant CLI创建，beta请求头是telemetry-destinations-2026-08-11，参数里traces.content_mode写metadata_only即可。

SDK追踪：先注册tracer provider

以Python为例，升级anthropic包并装opentelemetry-sdk，在第一次调用之前注册provider：

provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)
client = Anthropic()

控制台能看到anthropic.messages.create后，把ConsoleSpanExporter换成指向观测平台的OTLP exporter。常用的环境变量有三个：ANTHROPIC_OPEN_TELEMETRY=false关掉某个客户端的span；ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content记录内容；ANTHROPIC_OPEN_TELEMETRY_PROPAGATION=false停止发送traceparent头。官方提醒beta期间span名和选项可能改名，记得锁定SDK版本。

metadata_only和Full content怎么选

	Metadata only（默认）	Full content
包含	ID、耗时、状态、token数，以及你自己起的agent/工具名、MCP服务器名	以上全部，加提示词、回复、工具参数与结果
适合	看延迟、成本、失败率	复盘失败对话、用真实trace做评测
风险	低，但名字里别写客户信息	内容存到第三方平台，按对方的保留与权限策略管理
大小	很小	默认每span约0.75MB上限，超了会截断并标`anthropic.content.truncated`

两个容易漏的点：组织若与Anthropic有HIPAA、FERPA或K-12数据限制，destination无论怎么设都只导出元数据（SDK span不受影响）；开了零数据保留也能用Full content，但Managed Agents本身不适用零数据保留。我们的建议是生产先跑metadata_only两周，确认平台权限收紧了，再给单独workspace开Full content。

和Claude Code的可观测性是什么关系

是两套配置，数据可以汇到同一个平台。Claude Code走环境变量：CLAUDE_CODE_ENABLE_TELEMETRY=1开遥测，指标和事件分别用OTEL_METRICS_EXPORTER、OTEL_LOGS_EXPORTER；链路追踪仍是beta，要再加CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1和OTEL_TRACES_EXPORTER。它的span叫claude_code.interaction、claude_code.tool这一类，提示词默认脱敏。Platform这次的意义在于：你用API和Managed Agents自建的Agent，终于能和Claude Code、Cowork的数据放在同一个看板里。Agent SDK则是继承OTEL_*环境变量，不靠tracer provider。

上线后最常见的坑

trace是两截：要在自己的span里调用SDK，SDK会通过W3C traceparent把上下文传给API。Go和Java默认不注册propagator，要手动加。
每个请求出现两次：SDK span和API span同名，用span kind区分，CLIENT是SDK，SERVER是API。
token算重了：同一请求只汇总一个来源；有API span时以API span为准。
Delivery显示Failing：401/403多半是鉴权头，404是路径多写了/v1/traces。
destination变Disabled：端点返回3xx跳转、解析到内网IP，或连续24小时全部失败都会被停用，修好后要手动Enable。
拿trace对账：投递是best effort、至少一次，可能丢也可能重复。按Key核用量请用Usage API。

Node项目若用了@opentelemetry/auto-instrumentations-node，官方建议把SDK的propagation关掉，否则会出现两个traceparent头。

常见问题

Claude OpenTelemetry要额外收费吗？

公告没提单独计费；观测平台那边的存储费用另算，以各平台为准。

没有admin权限能用吗？

SDK追踪不需要权限。API追踪需要admin添加destination，developer角色只能查看。

一个组织最多几个destination？

10个，含已停用的；每个destination最多选1000个workspace、20个请求头。

能接国内的观测平台吗？

只要对方提供公网HTTPS的OTLP/HTTP端点就行，协议是标准的。但能否使用Claude Platform本身，仍取决于你所在地区是否受支持，见Claude API组织规则。

延伸：Langfuse（开源观测平台）、LangChain、AI工作流上线检查、模型网关选型、Claude Computer Use与Skills、AI开发与智能体；入口：Claude 开发者平台。

来源与核查日期

核查日期：2026-10-15（新加坡时间）。功能处于beta，字段与限制以官方文档当日版本为准。

Claude OpenTelemetry怎么开？Agent链路追踪步骤与坑