Claude API 接入 OpenTelemetry 追踪：分步配置指南

Anthropic 为 Claude API 推出了 OpenTelemetry 追踪的 Beta 版本。这意味着开发者现在可以把模型调用的链路信息，直接接入现有的可观测性体系。整个配置流程可以拆成三步：在代码中启用 SDK spans、为 API spans 添加 Console 目的地、以及只统计一次 token 用量。下面按这个顺序拆解具体做法和背后的设计意图。

为什么 Claude API 要原生支持 OpenTelemetry

在 LLM 应用里，一次用户请求往往牵涉多轮模型调用、工具执行和检索步骤。如果追踪数据散落在各家的私有格式里，排障时就得在多个面板之间来回切换。OpenTelemetry 作为云原生社区的事实标准，把 trace、span 的语义统一了下来，Claude API 直接导出 OTel traces，等于让模型调用成为分布式链路中的一个普通节点。

对已经在用 Jaeger、Tempo 或商业 APM 的团队来说，这个变化减少了自建埋点的工作量。之前要靠包装 SDK 手动记录请求耗时和 token 数，现在这部分信息由 API 侧直接产出，格式也符合 OTel 规范，接入成本明显下降。Beta 阶段功能范围可能还会调整，但方向已经明确：模型调用要能被标准工具链观测到。

OpenTelemetry 的核心数据模型由 trace、span 和 context propagation 三部分组成。一次完整的请求链路是一个 trace，链路中的每个操作节点是一个 span，span 之间通过 parent-child 关系构成树状结构。context propagation 则负责在服务边界传递 trace ID 和 span ID，使跨进程调用能被串联起来。Claude API 导出 OTel traces 时，正是把每次模型调用表示为一个 span，并接受调用方传入的上下文，从而将 API 调用挂到应用侧的 trace 树上。理解这套模型有助于判断 span 的层级设计是否合理：父 span 应代表业务步骤，子 span 代表具体的模型或工具调用。

OTLP（OpenTelemetry Protocol） 是 OTel 定义的标准数据传输协议，支持 gRPC 和 HTTP 两种传输方式。各类追踪后端（Jaeger、Tempo、商业 APM）以及 OpenTelemetry Collector 都实现了 OTLP 接收端。文章提到的 Console destination 可视为 OTLP exporter 的调试替代品，它不发送网络请求，而是把 span 数据打印到标准输出。在生产环境中，通常由 Collector 接收 OTLP 数据，再根据配置路由到不同后端，这样应用侧只需面向 OTLP 编程，不必绑定具体厂商。

第一步：在代码中创建 SDK spans

配置的起点是在应用代码里建立 SDK span。SDK span 描述的是你自己代码中的逻辑单元，比如一次业务处理、一轮对话编排，或者一次工具调用链。把 Claude API 的调用挂在这些 span 下面，就能在追踪视图里看清楚「哪段业务逻辑触发了模型请求、耗时多少」。

实际操作中，需要先初始化 OpenTelemetry 的 TracerProvider 和 exporter，再在调用 Claude API 的位置用 tracer 创建 span。建议把 span 的命名和业务语义对齐，例如用任务名而不是笼统的 claude-call，这样在链路列表里更容易定位问题。span 的属性和事件可以记录输入长度、模型名称等上下文，方便后续按维度筛选。

TracerProvider 与 exporter 的关系值得展开说明。TracerProvider 是 OpenTelemetry SDK 的入口对象，负责管理 tracer 实例、采样策略和资源属性（如 service.name）。Exporter 负责把已结束的 span 发送到目的地，常见实现包括 OTLP exporter、Console exporter 和各类厂商 exporter。初始化时，先创建 exporter，再把它注册到 TracerProvider 的 span processor 中，最后由 provider 生成 tracer。span processor 分为简单处理和批处理两类，批处理模式会缓冲 span 后批量导出，适合生产环境降低网络开销。在调用 Claude API 的位置，通过 tracer.start_as_current_span() 创建 span 并设为当前上下文，SDK 便会自动把 trace 上下文注入到对 Claude API 的请求中。

第二步：为 API spans 添加 Console 目的地

SDK spans 解决的是应用侧的可观测性，API spans 则来自 Claude API 服务端返回的追踪数据。Beta 版允许为 API spans 配置 Console 目的地，也就是把服务端产生的追踪信息输出到控制台。这一步在调试阶段特别有用：不用先搭好完整的后端收集器，就能直观看到 API 侧上报了哪些 span、包含哪些字段。

Console destination 更像是一个验证手段。确认数据结构符合预期之后，通常会把目的地换成真正的 OTLP exporter，把数据送入生产环境的追踪后端。原文强调的「add a Console destination for API spans」正是这个过渡步骤，先看到数据，再决定往哪里送。

第三步：token 只统计一次

追踪数据里重复计数是个容易踩的坑。如果 SDK 侧记录了一次 token 用量，API 侧又上报一次，汇总时就会翻倍。原文提到的「count tokens once」指向的就是这个一致性问题：token 统计应该只有一个可信来源，避免应用层和服务端各算各的。

在配置时，需要明确 token 指标归属哪一侧。比较稳妥的做法是让 API spans 携带权威的用量数据，应用侧只做引用而不重复累加。这样在成本分析和配额监控时，数字才对得上。Beta 阶段的具体字段命名可能变化，接入时以官方文档为准，但「单一数据源」这个原则不会变。

为什么 token 用量容易重复统计，与 LLM 调用的重试和流式响应机制有关。当请求因限流或超时被重试时，失败的尝试可能已经消耗了部分 token，而应用侧包装层往往在每次调用返回时累加用量，导致同一逻辑请求被计算多次。另一方面，流式响应下用量信息通常在流的末尾才完整返回，若应用侧提前估算、服务端又上报实际值，两者叠加同样会造成偏差。因此 token 指标应以 API 响应中返回的权威 usage 字段为准，应用侧只在该值缺失时做兜底估算，并在指标命名上区分「实际用量」与「估算用量」，避免在成本看板中混用。

接入时的几个实践建议

采样策略要提前定。 模型调用量大时，全量导出 traces 会给后端带来压力。可以在 TracerProvider 层配置采样率，或者对高价值请求做定向采样，兼顾成本和可观测性。

span 粒度别太细。 把每次 HTTP 请求都拆成独立 span 会让链路图变得嘈杂。按业务步骤划分粒度，排查问题时反而更高效。

Beta 功能留好退路。 配置可以做成开关，一旦字段或行为调整，能快速回滚到原有埋点方式。

小结

Claude API 的 OpenTelemetry 追踪 Beta 把模型调用纳入了标准可观测性体系。三步配置对应三个关注点：SDK spans 建立应用侧上下文、Console destination 验证 API spans 的数据形态、token 单一统计保证指标一致。对已经在用 OTel 的团队，这是一次低成本的接入机会；对还没建立追踪体系的团队，也可以借这个时机把 LLM 调用纳入统一观测。