监控¶

了解如何为 Claude Code 启用和配置 OpenTelemetry。

通过 OpenTelemetry (OTel) 导出遥测数据，追踪组织内 Claude Code 的使用量、成本和工具活动。 Claude Code 通过标准 metrics 协议导出时序指标，通过 logs/events 协议导出事件，可选通过 traces 协议导出分布式追踪。

快速开始¶

通过环境变量配置 OpenTelemetry：

# 1. 启用遥测
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. 选择导出器（两者都可选——仅配置需要的）
export OTEL_METRICS_EXPORTER=otlp       # 选项: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp          # 选项: otlp, console, none

# 3. 配置 OTLP 端点
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. 设置认证（如需要）
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. 调试用: 缩短导出间隔
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 秒（默认 60000ms）
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 秒（默认 5000ms）

# 6. 运行 Claude Code
claude

默认导出间隔为 metrics 60 秒、logs 5 秒。设置阶段可用更短间隔调试，生产环境记得恢复。

管理员配置¶

管理员可通过托管设置文件为所有用户配置 OpenTelemetry：

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

托管设置中定义的环境变量优先级高，用户无法覆盖。

Claude Code 不会将 OTEL_* 环境变量传递给它生成的子进程（Bash 工具、hooks、MCP 服务器、语言服务器）。

配置详情¶

常用配置变量¶

mTLS 认证¶

取决于 OTLP 协议：

指标基数控制¶

追踪（Beta）¶

分布式追踪导出 span，将每个用户提示词关联到它触发的 API 请求和工具执行。

默认关闭。启用方式：设置 CLAUDE_CODE_ENABLE_TELEMETRY=1 和 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1，然后设置 OTEL_TRACES_EXPORTER。

Span 默认脱敏用户提示词、工具输入和工具内容。设置 OTEL_LOG_USER_PROMPTS=1、OTEL_LOG_TOOL_DETAILS=1、OTEL_LOG_TOOL_CONTENT=1 以包含。

追踪激活时，Bash 和 PowerShell 子进程自动继承 TRACEPARENT 环境变量（W3C trace context）。

Span 层级¶

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (需要 detailed beta tracing)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Agent tool) subagent spans

动态头¶

企业环境需要动态认证时，可配置脚本生成头。 仅适用于 http/protobuf 和 http/json 协议。

在 .claude/settings.json 中添加：

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

脚本必须输出有效 JSON（字符串键值对），默认每 29 分钟刷新。

多团队组织支持¶

通过 OTEL_RESOURCE_ATTRIBUTES 添加自定义属性区分团队：

export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

可用指标和事件¶

标准属性¶

所有指标和事件共享以下属性：

指标¶

事件¶

Claude Code 通过 OpenTelemetry logs/events 导出以下事件：

事件关联属性¶

prompt.id（UUID v4）将同一用户提示词触发的所有事件关联起来。按 prompt.id 过滤可获取处理该提示词期间的全部 user_prompt、api_request 和 tool_result 事件。

工具决策事件的 source 值¶

解读指标和事件数据¶

使用量监控¶

成本监控¶

claude_code.cost.usage 支持按团队/个人跟踪趋势、识别高用量会话、按 skill.name/plugin.name/agent.name 归属支出。

成本指标是近似值。正式计费数据请参考 API 提供商（Claude Console、Amazon Bedrock 或 Google Cloud Agent Platform）。

审计安全事件¶

OpenTelemetry 事件是 Claude Code 活动的审计数据源。 每个事件携带身份属性，将工具调用、MCP 活动和权限决策关联到触发它们的用户。

将操作归属到用户¶

标准属性包含认证用户身份：user.email、user.account_uuid、user.account_id、organization.id。MCP 工具调用、Bash 命令和文件编辑归属于启动会话的开发者。

使用直接 API 密钥或第三方提供商时，只有 user.id 和 session.id 填充。此时通过 OTEL_RESOURCE_ATTRIBUTES 附加用户身份。

审计 MCP 活动¶

启用 logs 导出器并设置 OTEL_LOG_TOOL_DETAILS=1，每个 MCP 操作产生携带服务器名、工具名和调用参数的结构化事件。

发送事件到 SIEM¶

将 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 指向 SIEM 的 OTLP 接收器：

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"
  }
}

后端选择建议¶

指标后端¶

• 时序数据库（如 Prometheus）：速率计算、聚合指标
• 列存储（如 ClickHouse）：复杂查询、唯一用户分析
• 全功能可观测性平台（如 Honeycomb、Datadog、Grafana Cloud）：高级查询、可视化、告警

事件/日志后端¶

• 日志聚合系统（如 Elasticsearch、Loki）：全文搜索、日志分析
• 列存储（如 ClickHouse）：结构化事件分析
• 全功能可观测性平台：指标与事件关联

追踪后端¶

• 分布式追踪系统（如 Jaeger、Zipkin、Grafana Tempo）：span 可视化、请求瀑布图
• 全功能可观测性平台：追踪搜索和与指标/日志关联

服务信息¶

所有指标和事件携带以下资源属性：

• service.name: claude-code
• service.version: 当前 Claude Code 版本
• os.type: 操作系统类型
• os.version: 操作系统版本
• host.arch: 主机架构
• Meter Name: com.anthropic.claude_code

安全和隐私¶

• OpenTelemetry 导出是 opt-in 的，需要明确配置
• 原始文件内容和代码片段不包含在指标或事件中
• 通过 OAuth 认证时 user.email 包含在遥测属性中
• 用户提示词内容默认不收集，仅记录长度
• 助手响应文本默认不收集，仅记录长度
• 工具输入参数默认不记录
• 原始 API 请求/响应体默认不记录
• Claude 扩展思考内容始终从导出体中脱敏

在 Amazon Bedrock 上监控¶

详细的 Amazon Bedrock 监控指南参见 Claude Code Monitoring Implementation (Amazon Bedrock)。

ROI 测量资源¶

综合 ROI 测量指南参见 Claude Code ROI Measurement Guide。