可观测性（OpenTelemetry）

Agent SDK 通过 OpenTelemetry 将追踪、指标和日志事件导出到任意 OTLP 兼容后端（Honeycomb、Datadog、Grafana、Langfuse 等）。遥测数据由 Claude Code CLI 子进程直接导出，SDK 本身不产生遥测。

核心机制

三种信号：

信号	内容	启用方式
Metrics	token/费用/会话计数器	OTEL_METRICS_EXPORTER
Log events	prompt/API 请求/工具结果结构化记录	OTEL_LOGS_EXPORTER
Traces（beta）	交互/模型请求/工具调用 span	OTEL_TRACES_EXPORTER + CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1

配置方式：通过环境变量传递，支持进程级全局配置或通过 options.env 按调用配置。TypeScript 中 env 完全替换继承环境，需显式包含 ...process.env。

Trace Span 层级：

• claude_code.interaction：一轮 Agent 循环
• claude_code.llm_request：每次 Claude API 调用
• claude_code.tool：每次工具调用（含 tool.blocked_on_user 和 tool.execution 子 span）
• claude_code.hook：每次 Hook 执行（需额外 beta 配置）

关键细节

基础配置：

OTEL_ENV = {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",  # Traces 需要
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4318",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-token",
}
options = ClaudeAgentOptions(env=OTEL_ENV)

缩短导出间隔（短任务防数据丢失）：

OTEL_ENV.update({
    "OTEL_METRIC_EXPORT_INTERVAL": "1000",
    "OTEL_LOGS_EXPORT_INTERVAL": "1000",
    "OTEL_TRACES_EXPORT_INTERVAL": "1000",
})

标记终端用户（多租户场景）：

env={"OTEL_RESOURCE_ATTRIBUTES": f"enduser.id={quote(user_id)},tenant.id={quote(tenant_id)}"}

敏感数据控制（默认不记录内容）：

• OTEL_LOG_USER_PROMPTS=1：记录 prompt 文本
• OTEL_LOG_TOOL_DETAILS=1：记录工具参数（文件路径、命令等）
• OTEL_LOG_TOOL_CONTENT=1：记录完整工具输入输出（需启用 Traces）

与其他概念的关联

• cost-tracking - 从消息流直接读取 token 用量（不需要外部后端）
• hosting - 容器级别设置环境变量
• agent-loop - Trace span 对应的循环阶段

实践要点

• 不要将 console 设为 exporter，SDK 使用 stdout 作为消息通道会冲突
• 本地调试可用 Jaeger 容器作为 OTLP 接收端
• W3C trace context 自动传播：应用中有活跃 span 时，Agent 的 trace 会作为子 span 出现
• 敏感数据（prompt 内容、工具输出）默认不记录，需显式启用对应变量
• OTEL_RESOURCE_ATTRIBUTES 中的值需要 percent-encode（逗号、空格、等号是保留字符）