OpenTelemetry 监控配置

是什么

monitoring-usage 描述如何通过 OpenTelemetry（OTel）导出 Claude Code 的用量、成本和工具活动数据。支持 metrics（时序数据）、logs/events 和 traces（分布式追踪，beta）三种信号类型。

核心机制

快速启用

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

关键环境变量

变量	说明	默认值
CLAUDE_CODE_ENABLE_TELEMETRY	启用遥测（必须）	未设置
OTEL_METRICS_EXPORTER	metrics 导出器：otlp/prometheus/console/none	-
OTEL_LOGS_EXPORTER	logs 导出器：otlp/console/none	-
OTEL_METRIC_EXPORT_INTERVAL	metrics 导出间隔（ms）	60000
OTEL_LOGS_EXPORT_INTERVAL	logs 导出间隔（ms）	5000
OTEL_LOG_USER_PROMPTS	记录用户 prompt 内容	禁用
OTEL_LOG_TOOL_DETAILS	记录工具参数和输入	禁用
OTEL_LOG_RAW_API_BODIES	导出完整 API 请求/响应 JSON	禁用

管理员集中配置 通过 managed settings 文件统一下发 OTel 配置，用户无法覆盖 env 块中的环境变量。

Traces（beta） 需同时设置 CLAUDE_CODE_ENABLE_TELEMETRY=1 和 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1，再设 OTEL_TRACES_EXPORTER。

Span 层级：

claude_code.interaction（根 span）
  ├── claude_code.api_call
  └── claude_code.tool（工具调用）
       ├── permission_wait
       └── execution

Cardinality 控制

• OTEL_METRICS_INCLUDE_SESSION_ID：默认 true
• OTEL_METRICS_INCLUDE_ACCOUNT_UUID：默认 true
• OTEL_METRICS_INCLUDE_VERSION：默认 false

关键细节

• OTel 变量不传递给子进程（Bash tool、hooks、MCP servers），子进程需单独配置
• mTLS：http/protobuf 用 CLAUDE_CODE_CLIENT_CERT/KEY，grpc 用 OTEL_EXPORTER_OTLP_CLIENT_KEY/CERTIFICATE
• 调试时缩短导出间隔（如 10s），生产环境恢复默认值
• 非交互式 session（-p 标志）支持从环境读取 TRACEPARENT/TRACESTATE 实现分布式追踪

与其他概念的关联

• analytics - 仪表盘级别的用量分析
• costs - 成本追踪
• server-managed-settings - 集中下发 OTel 配置

实践要点

• OTEL_LOG_RAW_API_BODIES 会暴露完整对话历史，启用前评估数据安全影响
• Prometheus exporter 适合已有 Prometheus 栈的团队
• 大规模部署时降低 cardinality（关闭 session_id 维度）以控制存储成本