Agent 出问题，几乎都是事后才知道。它没按你预期走，你才开始翻记录、拼时间线，猜是哪一步拐错了弯。 Agent 是软件。它循环、不确定，但确实跑在生产环境里，在人工检查点之间自己做决定。所以一次运行变得奇怪时，你需要的东西和排查任何分布式系统一样：一份按步骤记录下来的、实际发生了什么的账本。 2026 年 10 月 14 日 ，Anthropic 宣布为 Claude 平台提供 OpenTelemetry（OTel）追踪，处于公开测试阶段。这次落地的东西包括：Claude Managed Agents、Messages API 和 Claude SDK 都能为请求、模型调用、Agent 轮次和工具使用（含 MCP 工具调用）发出 OpenTelemetry span。 这些 span 使用 OpenTelemetry GenAI 语义约定里的属性，支持该约定的平台不用额外配置就能识别。追踪数据可以发往任何接受 OTLP 的平台，合作方名单里有 Datadog、Grafana Cloud、Honeycomb、Sentry、Splunk、New Relic、Langfuse、LangSmith、Braintrust、Arize AI 等。 注意这是 beta。文档明确提醒，span 名称、属性和 SDK 选项都可能变，建议锁定 SDK 版本。 span 有两个来源，配置方式不一样。 API 追踪在 Claude Console 里配。管理员添加一个目的地，API 就会为 Messages API 请求、请求内的每次模型运行、Managed Agents 轮次以及 API 运行的服务端工具发出 span。 SDK 追踪发生在你的应用里。SDK 会为它发出的请求和工具运行器执行的客户端工具发出 span，但它自己不导出任何东西。你的应用要注册一个 OpenTelemetry tracer provider 和一个 exporter，由 exporter 把 span 送到你的平台。如果你的服务已经配好了 OpenTelemetry，SDK 会直接用你注册的 tracer provider。 两边都配上，一个请求的 SDK span 和 API span 会落进同一条追踪里。 为什么追踪适合 Agent？ 一次 Agent 运行不是一个请求。它是一次模型调用，然后一次工具调用，然后是基于工具返回结果的又一次模型调用，如此重复，直到 Agent 认为做完了。一条用户消息可以扇出成十几步。 没有 trace ID 和 span ID 的普通日志行，只会让你在脑子里重建顺序：哪个工具调用跟在哪个模型调用后面，哪一步耗了时间，运行在哪一步拐向了你没预料的方向。日志也能携带追踪上下文和结构化字段，关联日志也有帮助。追踪只是直接把时间线给你。 在一条追踪里，每一步是一个带自己时序和属性的 span。在简化的应用追踪中，模型请求和工具使用会作为有序的兄弟节点，挂在一个包住整次运行的 span 下面。具体层级取决于埋点方式。Anthropic 自己的示例追踪里，中间还夹着工具运行器和请求的 span。父子链接不能证明某一步导致了另一步，所以要读顺序和属性，不能只看形状。 平台 span 告诉你模型和工具做了什么，但告诉不了你别的。 它们不知道你的应用跑的是哪个 prompt 版本，哪个功能开关是开着的，哪个客户撞上了这个问题。这些上下文在你的代码里，得你自己加。 做法是在你自己的 Agent 轮次外面套一个 span。在里面调用 SDK 时，SDK 的 span 会嵌在你的 span 下面。属性名可以按团队习惯自己定。值得挂上去的有四类： Prompt 版本 ：行为一变，第一个想知道的就是它。是 prompt 改了，还是别的东西改了？ 功能开关取值 ：一个开关能把一次运行带上完全不同的路径。不记在追踪上，同样输入的两次运行会显得莫名其妙地不一样。 客户引用 ：方便拉出某个账号的所有运行。用带密钥的引用或不透明 token，绝不用原始 ID。把它当作假名化数据，不是匿名数据。 过滤后的工具调用参数 ：工具返回了错东西时很有用，但参数里可能有邮箱、密钥或整份文档。只记录白名单里的字段，其余省略或脱敏。截断一个字段，密钥仍可能留在里面。 过滤你自己加的属性，并不会净化自动捕获的内容。SDK 和 API 的内容设置要单独检查。 内容要不要离开你的系统，得自己定。 平台 span 有自己的内容设置。默认是仅元数据模式：标识符、时序、状态、token 计数，以及你选的名字，比如工具名和 Agent 名。完整内容模式会加上 prompt、响应，以及工具调用的参数和结果。 完整内容对调试最有用，同时也意味着你的可观测平台现在要按它自己的访问和保留规则来存 prom
