管理OpenTelemetry

适用于 Claude API 的 OpenTelemetry

Copy page



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

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

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

入门

您可以设置 SDK 追踪、API 追踪，或两者都设置。同时设置两者，即可在同一追踪中看到请求的 SDK span 和 API span，如示例追踪所示。对于发往 Claude Platform on AWS 的请求，API span 则位于各自独立的追踪中。

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

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

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

内容模式

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

• Metadata only（SDK 中为 metadata_only）：默认值。span 包含标识符、时间、状态、令牌计数以及您选择的文本，例如您的智能体和工具的名称与描述，以及您的 MCP 服务器的名称。
• Full content（SDK 中为 content）：可见性最高。span 包含模型提示和响应，以及 Metadata only 中的所有内容。

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

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

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

内容限制

使用 Full content 时，默认情况下每个 span 最多包含 0.75 MB 的内容。该默认值可容纳以英文文本填满的 200k 令牌上下文窗口，同时仍低于许多可观测性平台和代理的 1 MB 请求限制。如果您选择合作伙伴平台作为 Provider，Console 会设置该平台所接受的限制。

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

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

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

在 SDK 中，请设置 traces.max_content_bytes。在 Console 中，请在添加目标时将 Content mode 设置为 Full content，然后在 Advanced settings 下设置 Maximum content size in 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. 在第二个请求中，模型给出最终答案。

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

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

使用 Full content 时，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）。

您应用程序中的 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 已包含从提示缓存读取和写入提示缓存的令牌，因此不要再将缓存属性加到其中。有关所有用量属性，请参阅令牌用量。