MLflow Blog

How to trace Claude agents via Native OpenTelemetry Export

7.1内容质量
How to trace Claude agents via Native OpenTelemetry Export

TL;DR · AI 摘要

How to trace Claude agents via Native OpenTelemetry Export MLflow How to trace Claude agents via Native OpenTelemetry Ex...

核心要点

  • 主题聚焦：How to trace Claude agents via Native OpenTeleme
  • 来源：MLflow Blog，建议结合原文判断细节。
  • AI 分析暂不可用，本条为保底评分与摘要。
#AI#编程#前端#后端#安全
打开原文

如何通过原生 OpenTelemetry 导出追踪 Claude 代理 | MLflow

如何通过原生 OpenTelemetry 导出追踪 Claude 代理

2026 年 10 月 14 日

·

9 分钟阅读

Joshua Wong

Databricks 软件工程师

基于 Claude 构建的代理可以在单个任务上运行数十轮：调用模型、运行工具，并在每一步之后再次调用模型。当运行出现错误时，最终答案很少能告诉你原因。哪个工具调用返回了意外结果？那个长时间运行的步骤实际消耗了多少 token，成本是多少？

Claude 现在可以原生回答这些问题。Claude 托管代理、Messages API、Claude SDK 以及 Claude Code 都会发出 OpenTelemetry（OTel）追踪，覆盖每个模型请求和工具调用，任何使用 OpenTelemetry 协议（OTLP）的后端都可以接收这些追踪。你不需要适配器代码，也不需要收集器。

本教程将展示如何为每个 Claude 产品设置该导出功能。我们选择将追踪发送到 MLflow，因为它开源且无需为任何服务注册。

整体架构 ​

Claude 通过 HTTP 使用 OTLP 发送追踪。在本教程中，这些追踪会发送到本地 MLflow 服务器，服务器通过 /v1/traces 接收：

code
+----------------+                         +---------------+            +------------+
|  Claude Code   |                         | MLflow server |            |   MLflow   |
|   Agent SDK    |        OTLP/HTTP        |               |            | tracing UI |
|  Claude SDKs   | ----------------------> |   translates  | ---------> |            |
|  Messages API  |     POST /v1/traces     |  Claude spans |            |            |
| Managed Agents |                         |               |            |            |
+----------------+                         +---------------+            +------------+

SDK 导出与平台导出的区别 ​

  • 平台导出：配置 Claude 平台将服务器端模型运行、托管代理轮次和服务器工具活动发送到 MLflow。
  • SDK 导出：捕获 SDK 请求、本地工具活动和应用中的自定义追踪。需要单独配置其导出器和内容模式。
  • 同时使用：将两者发送到同一个 MLflow 实验，以连接客户端和服务器端追踪。AWS 上的 Claude 平台会将 API 追踪保留在独立的追踪中。

详见 Anthropic 的 OpenTelemetry 指南。

先决条件 ​

  • 服务器端安装 MLflow 3.17.1 或更新版本（pip install "mlflow>=3.17.1"）
  • 要追踪的 Claude 产品

步骤 1：启动 MLflow 服务器并创建实验 ​

本地启动 MLflow 服务器：

code
mlflow server --host 127.0.0.1 --port 5000

为你的追踪创建实验（mlflow experiments create -n claude-traces），并记录其数字 ID。下一步将该 ID 传递给 Claude，以指定追踪属于哪个实验。

步骤 2：通过 OTLP 发送 Claude 追踪 ​

所有产品都向同一地址发送追踪：MLflow 端点 http://<your-server>/v1/traces，请求头需包含 x-mlflow-experiment-id: <your experiment ID> 。

Claude 平台 UI：Messages API 和托管代理 ​

在 Claude 平台中，打开 OpenTelemetry → + 添加目标并选择自定义。将端点设置为 https://YOUR_MLFLOW_SERVER/v1/traces，添加 x-mlflow-experiment-id 请求头和实验 ID，以及任何认证请求头。

使用远程 MLflow 服务器

平台导出功能无法访问仅在本地机器（localhost）上运行的服务器。请设置一个远程 MLflow 服务器，其 HTTPS 端点可供 Anthropic 访问，或使用 Databricks、AWS 或 Red Hat 提供的托管 MLflow 服务。

选择 Full content 以记录消息和工具内容以便进行更深入的分析和评估，或选择 Metadata only 以获取延迟和令牌数量等统计信息。选择您的工作区并点击 Add destination。

Claude SDK 和 Messages API

Claude SDK 为每次 Messages API 调用创建一个 OpenTelemetry 跟踪跨度。与其他原生支持 OpenTelemetry 的库类似，它们会将跨度发送到应用程序设置的任何导出器，因此唯一需要的操作是在创建客户端之前将 OpenTelemetry 导出器指向 MLflow。

Python:

bash
pip install anthropic opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
python
import anthropic
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="http://127.0.0.1:5000/v1/traces",
            headers={"x-mlflow-experiment-id": "YOUR_EXPERIMENT_ID"},
        )
    )
)
trace.set_tracer_provider(provider)

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

TypeScript:

bash
npm install @anthropic-ai/sdk @opentelemetry/sdk-trace-node@^2.11.0 @opentelemetry/sdk-trace-base@^2.11.0 @opentelemetry/exporter-trace-otlp-proto@^0.222.0
typescript
import Anthropic from "@anthropic-ai/sdk";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";

const provider = new NodeTracerProvider({
  spanProcessors: [
    new BatchSpanProcessor(
      new OTLPTraceExporter({
        url: "http://127.0.0.1:5000/v1/traces",
        headers: { "x-mlflow-experiment-id": "YOUR_EXPERIMENT_ID" },
      })
    ),
  ],
});
provider.register();

const client = new Anthropic();
const message = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
});

Claude 管理代理

Claude 管理代理在 Anthropic 的基础设施上运行。将 OTLP 跟踪端点设置为您的 MLflow 服务器的 /v1/traces URL，并添加标头 x-mlflow-experiment-id: <your experiment ID>。如果跟踪数据是从 Anthropic 侧发送的，服务器需要一个 Anthropic 可访问的 URL；在公开该服务器之前，请先启用 MLflow 认证。

Claude Code

Claude Code 的 OTel 导出完全通过环境变量进行配置。前六个变量是必需的；最后三个是可选的。将它们添加到您的 shell 配置中（或添加到您启动 claude 前加载的 .env 文件中）：

code
# 必须操作：启用遥测功能并开启追踪跨度
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
# 必须操作：通过HTTP使用OTLP导出追踪
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
# 必须操作：配置MLflow端点（注意完整的/v1/traces路径）以及
# 告诉MLflow存储追踪的x-mlflow-experiment-id请求头
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:5000/v1/traces
export OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-mlflow-experiment-id=YOUR_EXPERIMENT_ID
# 可选操作：包含默认会被过滤的提示内容和工具内容
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_TOOL_DETAILS=1
export OTEL_LOG_TOOL_CONTENT=1

启动Claude并正常工作；当会话结束时，追踪信息会出现在你的MLflow实验中。

Claude Agent SDK

Claude Agent SDK（Python和TypeScript版本）将Claude Code CLI作为子进程运行，并向其传递配置，因此它使用上面Claude Code的配置：在启动SDK的进程中设置这些环境变量，每个SDK会话将生成相同的追踪。

Python：SDK会将其env选项合并到继承的环境变量中，因此在运行脚本前导出变量即可：

code
import
asyncio
from
claude_agent_sdk
import
ClaudeAgentOptions
,
query
async
def
main
(
)
:
# 上面的OTel环境变量会被CLI子进程继承
# 因此不需要SDK特定的配置
async
for
message
in
query
(
prompt
=
"Summarize the failing tests in this repo"
,
options
=
ClaudeAgentOptions
(
)
,
)
:
print
(
message
)
asyncio
.
run
(
main
(
)
)

TypeScript：一个实际的陷阱：options.env会替换子进程环境而不是扩展它。如果你传递env对象，请先展开process.env，否则你的OTel变量将无法到达CLI：

code
import
{
query
}
from
"@anthropic-ai/claude-agent-sdk"
;
for
await
(
const
message
of
query
(
{
prompt
:
"Summarize the failing tests in this repo"
,
options
:
{
env
:
{
// options.env会替换环境，因此需要显式继承：
...
process
.
env
,
CLAUDE_CODE_ENABLE_TELEMETRY
:
"1"
,
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA
:
"1"
,
OTEL_TRACES_EXPORTER
:
"otlp"
,
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
:
"http/protobuf"
,
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
:
"http://127.0.0.1:5000/v1/traces"
,
OTEL_EXPORTER_OTLP_TRACES_HEADERS
:
"x-mlflow-experiment-id=YOUR_EXPERIMENT_ID"
,
OTEL_LOG_USER_PROMPTS
:
"1"
,
OTEL_LOG_TOOL_DETAILS
:
"1"
,
OTEL_LOG_TOOL_CONTENT
:
"1"
,
}
,
}
,
}
)
)
{
console
.
log
(
message
)
;
}

SDK的两个注意事项：

  • 不要通过SDK使用console OTel导出器。SDK和CLI通过stdout通信，console导出会破坏该通道。请使用如示例所示的otlp导出器。
  • 默认情况下导出失败会静默处理。如果追踪未到达，请设置CLAUDE_CODE_OTEL_DIAG_STDERR=1以在stderr获取OTel诊断信息，而不是猜测问题。

第3步：在MLflow中检查追踪

打开实验的Traces标签页。每个代理运行或请求都会显示为一个追踪，行内显示总token数和成本。点击追踪可查看每个模型调用和工具调用的步骤，包含输入、输出和token计数。

深入使用Claude Code：响应文本和上下文快照

默认情况下，Claude Code 的模型请求跨度会携带令牌数量但不包含模型的响应文本，且发送给模型的完整上下文也不会包含在导出数据中。针对这种情况，Claude Code 提供了额外的详细追踪模式。设置以下内容：

code
export ENABLE_BETA_TRACING_DETAILED=1
export BETA_TRACING_ENDPOINT=http://127.0.0.1:5000/v1/traces

将添加 response.model_output（模型的回复）、new_context（上下文快照）、tool_input（完整的工具输入）以及一些系统提示属性。此时模型的回复会作为模型调用的输出显示：

故障排除

  • 没有看到 Claude Code 的追踪记录。请确认已设置 CLAUDE_CODE_ENABLE_TELEMETRY 和 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA 两个参数。前者是主控开关，后者用于启用跨度追踪。设置 CLAUDE_CODE_OTEL_DIAG_STDERR=1 可查看导出器错误信息。
  • Claude Code 的追踪记录中所有内容都是 <REDACTED>。这是默认的隐私保护设置；请从第 2 步中设置 OTEL_LOG_* 参数来调整。

总结

现在你的 Claude 代理会告诉你它们执行了什么操作。由于该设置使用的是标准 OTLP 协议，因此与其他 OTLP 后端的集成方式完全相同，只需更改端点和请求头即可。

准备好亲自尝试了吗？

  • 通过 MLflow Tracing 快速上手，捕获并检查你自己的代理运行记录。
  • 通过演示实验探索 MLflow 中的追踪功能，无需搭建服务器。
  • 阅读 OpenTelemetry 指南了解 OTLP 配置和集成细节。

有问题或反馈？在 Slack 社区与我们交流，或提交 GitHub 问题。