适用于 Claude API 的 OpenTelemetry 追踪

使用来自 Anthropic SDK 和 Claude API 的 OpenTelemetry span 追踪您的 Messages API 请求、工具使用和 Managed Agents 会话。

Claude API 和 SDK 可以使用 OpenTelemetry(OTel)追踪您的 Messages API 请求、工具使用和 Managed Agents 会话。您可以在已有的可观测性平台中查看这些追踪。您可以使用它们调试失败或缓慢的请求、跟踪令牌消耗和延迟,并基于真实流量构建评估。您还可以在应用程序自身的追踪中看到每个请求,并将其关联到发送该请求的用户或功能。

OpenTelemetry 是一个大多数可观测性平台都支持的供应商中立标准。"trace"(追踪)是一个请求在您的系统中的完整记录。"span"(跨度)是追踪中的一个步骤,例如一次模型请求或一次工具使用。API 和 SDK 使用 GenAI 语义约定中的属性,因此支持这些约定的平台无需额外设置即可识别这些 span。

入门

您可以设置 SDK 追踪、API 追踪,或两者都设置。同时设置两者,即可在同一追踪中看到请求的 SDK span 和 API span,如示例追踪所示。

让 Claude Code 为您设置此功能

示例代码
使用 Claude API 和 Anthropic SDK 设置 OpenTelemetry 追踪
您获得的内容SDK 追踪API 追踪两者结合
Messages API 请求✅✅✅
Sessions API 请求✅✅✅
令牌用量(参见令牌统计)✅✅✅
请求中的每次模型运行—✅✅
Managed Agents 轮次—✅✅
由 API 运行的服务器工具—✅✅
由工具运行器运行的客户端工具✅—✅
自托管沙箱中的工具✅—✅
其他 API 请求,例如上传文件✅—✅
设置代码Console两者
所需权限无管理员管理员
覆盖范围使用 SDK 的客户端任何客户端任何客户端
云平台支持任何Claude Platform
Claude Platform on AWS
Claude Platform
Claude Platform on AWS

对于 Claude Code、Agent SDK 或 Cowork,请参阅 Claude Code 监控、Agent SDK 可观测性或 Cowork 活动监控。

将追踪发送到合作伙伴平台

将追踪发送到任何接受 OTLP 的可观测性平台,包括以下合作伙伴:

Arize AI

面向 AI 的统一可观测性与评估平台。

Braintrust

面向智能体的主动可观测性平台。

Databricks

面向可观测性与评估的统一 AI 控制平面。

Datadog

AI 驱动的可观测性与安全。

Dynatrace

为 AI 时代打造的可观测性。

Elastic

基于开源构建的可观测性。

Honeycomb

面向软件新形态的可观测性平台。

Langfuse

开源的智能体可观测性与评估平台。

PostHog

用于构建成功产品的一体化平台。

Sentry

调试出错的代码和行为异常的智能体。

Snowflake

内置可观测性与治理的智能体控制平面。

Splunk

观测、评估并保护智能体。

内容模式

每个目标和每个 SDK 客户端都有一个内容模式,用于设置 span 是否包含模型提示和响应。请在添加目标或配置 SDK 时进行设置。

  • 仅元数据(SDK 中为 metadata_only):默认值。span 包含标识符、时间、状态、令牌计数以及您选择的文本,例如您的智能体和工具的名称与描述,以及您的 MCP 服务器的名称。
  • 完整内容(SDK 中为 content):可见性最高。span 包含模型提示和响应,以及"仅元数据"中的所有内容。

使用"完整内容",您还可以查看运行失败或缓慢的原因、阅读完整对话,并基于真实追踪构建评估。在 OpenTelemetry span 参考中,包含提示和响应的属性会标记为

内容
。

如果您的组织与 Anthropic 之间存在 HIPAA、FERPA 或 K-12 数据处理限制,则无论目标的内容模式如何,目标都只导出元数据。SDK span 不受影响。

启用零数据保留后,您仍然可以使用"完整内容"。对于 Messages API 请求,API 仅将导出的内容保留在内存中,直到将其传送到目标。Claude Managed Agents 不符合零数据保留的条件,并且在您使用 OpenTelemetry 时,其数据保留方式保持不变。

内容限制

使用"完整内容"时,每个 span 默认最多保存 0.75 MB 的内容。这足以容纳 200k 令牌上下文窗口的英文文本,并且低于许多可观测性平台和代理的 1 MB 请求限制。如果您选择合作伙伴平台作为提供商,Console 会设置该平台可接受的限制。

当内容超过限制时,SDK 或 API 会缩短内容,并将 anthropic.content.truncated 设置为 true。请求 span 会先移除系统提示和最早的消息,工具 span 会从结果末尾移除块。图像和文档仅显示其类型。

在以下情况下更改此限制:

  • 您的可观测性平台可接受更大的有效负载: 提高或移除限制,以完整保留较长的提示和响应。填满 1M 令牌上下文窗口大约需要 4 MB。
  • 您的可观测性平台或其前面的代理会拒绝较大的请求: 降低限制。

在 SDK 中,请设置 traces.max_content_bytes (typescript, java, php: traces.maxContentBytes; csharp: Traces.MaxContentBytes; go: option.WithOpenTelemetryTracesMaxContentBytes())。在 Console 中,请在添加目标时将内容模式设置为完整内容,然后在高级设置下设置最大内容大小(MB)。

示例追踪及其解读方法

Messages API 请求

在创建消息的请求的 API span 之下,API 会为每次模型请求添加一个 span,并为 API 运行的每次服务器工具或 MCP 连接器工具使用添加一个工具 span。

在此示例中,您的应用程序调用了工具运行器,即运行您的工具并将其结果发送回 Claude 的 SDK 辅助工具。工具运行器发送的每个请求都有一个来自 SDK 的客户端 span 和一个来自 API 的服务器 span。这些 span 按以下顺序出现:

  1. 您的应用程序启动 answer_question span,并在其中调用 Messages 工具运行器(显示为 anthropic.messages.tool_runner span)。
  2. 工具运行器发送第一个请求(显示为第一个 anthropic.messages.create 客户端 span 及其下的 span)。在此请求中,API 在两次模型请求之间运行网络搜索工具。
  3. 在第二次模型请求中,模型请求使用自定义的 get_weather 工具,因此第一个请求结束。
  4. 工具运行器运行 get_weather(显示为 anthropic.custom_tool_use get_weather span)。
  5. 工具运行器发送带有工具结果的第二个请求(显示为第二个 anthropic.messages.create 客户端 span 及其下的 span)。
  6. 在第二个请求中,模型给出最终答案。

Messages 工具运行器 trace(追踪)示例:两个请求,包含客户端和服务器 span(跨度)、模型请求、web_search 和 get_weather

您应用程序中的 SDK 会发出 anthropic.messages.tool_runner span、anthropic.custom_tool_use span 以及每个请求的客户端 span。要获取这些 span,请设置 SDK 追踪。

每个请求的令牌用量会出现在其多个 span 上。要确保每个令牌只计算一次,请参阅令牌统计。

使用完整内容时,anthropic.messages.create 服务器 span 包含提示和响应。系统提示位于 gen_ai.system_instructions 中,请求的消息位于 gen_ai.input.messages 中,响应位于 gen_ai.output.messages 中。

有关每个 span 及其属性,请参阅 OpenTelemetry span 参考。

Managed Agents 会话

会话中的每个 Sessions API 请求都有一个 span,每个智能体轮次都有一个轮次 span。由某个请求启动的轮次是该请求 span 的子级。一个轮次包含每个模型请求以及 API 运行的每个工具的 span,但工具 span 参考中列出的情况除外。它还包含每次结果评估的 span。

此示例跟踪一个聊天请求,在该请求中,您的应用程序向会话发送一条消息并运行一个自定义工具。该 trace 包含来自您的应用程序和 API 的 span,顺序如下:

  1. 您的应用程序收到来自用户的 POST /chat 请求。
  2. 您的应用程序启动 SDK 的会话工具运行器,该运行器列出并流式传输会话的事件(显示为 anthropic.sessions.events.stream 和 anthropic.sessions.events.list span)。
  3. 您的应用程序通过调用 sessions.events.send 将用户的消息发送到会话。
  4. 一个轮次开始,其中包括模型请求、一次 bash 工具使用,以及另一个线程上的一个轮次(显示为第一个 anthropic.session.turn span 及其下的 span)。
  5. 模型请求使用自定义工具 list_issues,因此该轮次以停止原因 requires_action 结束。
  6. 会话工具运行器运行 list_issues(显示为 anthropic.custom_tool_use list_issues span),并通过调用 sessions.events.send 发送其结果。
  7. 第二个轮次以工具结果开始(显示为最后一个 anthropic.session.turn span)。

Managed Agents 会话 trace(追踪)示例:POST /chat、四个会话事件请求、三个轮次、一次 bash 工具使用以及 list_issues

您应用程序中的 SDK 会发出 anthropic.custom_tool_use span 以及每个请求的客户端 span。要获取这些 span,请设置 SDK 追踪。

一个会话的 span 可能分布在多个 trace 中,例如当您从新的根 trace 发送后续请求时。启用 multiagent(多智能体)后,一个会话还可以有多个线程。要找到您需要的 span,请按 ID 对它们进行分组。

  • 单个线程: 按 gen_ai.conversation.id 对 span 进行分组,该属性保存会话线程 ID。按开始时间对它们排序,即可将线程作为对话记录阅读。
  • 整个会话及其所有线程: 跨 trace 按 anthropic.session.id 对 span 进行分组。

使用完整内容时,您可以从会话的 span 中读取其内容。

  • 要读取某个轮次的内容,请使用其轮次 span。系统提示位于线程第一个轮次 span 的 gen_ai.system_instructions 中,输入位于 gen_ai.input.messages 中(您的消息和工具结果、system.message 事件以及来自其他线程的消息),输出位于 gen_ai.output.messages 中(智能体的消息、工具使用和工具结果)。
  • 要查看某次工具使用的参数和结果,请读取其工具 span。参数位于 gen_ai.tool.call.arguments 中,结果位于 anthropic.tool_result.content 中。

有关每个 span 及其属性,请参阅 OpenTelemetry span 参考。

令牌统计

要使每个令牌只计数一次,请对每个请求仅汇总一个来源的 span。当一个 Messages API 请求同时具有 SDK span 和 API span 时,请汇总其 API span。两者都命名为 anthropic.messages.create,因此请按类型区分它们:SDK span 为 CLIENT,其子级 API span 为 SERVER。

对于每个来源,请仅汇总以下 span,因为某些用量属性会在 API span 的多个层级上重复出现:

  • SDK span: 汇总 anthropic.messages.create span。如果请求包含 compaction(压缩),还需加上该 span 的 anthropic.usage.compaction.input_tokens 和 anthropic.usage.compaction.output_tokens,因为 gen_ai.usage.* 属性不包含压缩令牌。如果请求由备用模型处理,其 span 仅包含实际提供响应的模型的用量。
  • Messages API 请求的 API span: 汇总 anthropic.messages.create span 或其 anthropic.model_request span,但不要两者都汇总。如果请求包含压缩,还需加上其 anthropic.compaction span。不要再额外加上 anthropic.messages.create span 的 anthropic.usage.compaction.* 属性,因为它们包含相同的令牌。
  • Managed Agents 会话的 API span: 汇总 anthropic.model_request 和 anthropic.session.outcome_evaluation span。

span 可能会多次到达,例如当投递被重试时。如果您的可观测性平台不会删除重复项,请按 trace ID 和 span ID 对每个 span 只计数一次。

gen_ai.usage.input_tokens 已包含从提示缓存读取和写入提示缓存的令牌,因此不要再将缓存属性加到其中。有关所有用量属性,请参阅令牌用量。

可用性

OpenTelemetry在所有模型上处于 beta 阶段。

API 支持

Messages API

  • 可用性:可用
状态云平台模型
Beta所有支持的平台所有模型

Managed Agents

  • 可用性:可用
状态云平台模型
Beta所有支持的平台所有模型
文档内容持续同步更新