OpenTelemetry 支持目前处于测试阶段,详细信息可能会发生变化。

Claude Code 中的 OpenTelemetry

Claude Code 支持 OpenTelemetry (OTel) 指标用于监控和可观测性。本文档解释了如何为 Claude Code 启用和配置 OTel。

所有指标都是通过 OpenTelemetry 的标准指标协议导出的时间序列数据。用户有责任确保其指标后端配置正确,并且聚合粒度满足其监控要求。

快速开始

使用环境变量配置 OpenTelemetry:

# 1. 启用遥测
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. 选择导出器
export OTEL_METRICS_EXPORTER=otlp       # 选项:otlp, prometheus, console

# 3. 配置 OTLP 端点(用于 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. 用于调试:减少导出间隔(默认:600000ms/10分钟)
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 秒

# 6. 运行 Claude Code
claude

默认导出间隔为 10 分钟。在设置过程中,您可能希望使用较短的间隔进行调试。请记住在生产环境中重置此设置。

有关完整配置选项,请参阅 OpenTelemetry 规范

管理员配置

管理员可以通过托管设置文件为所有用户配置 OpenTelemetry 设置。这允许在整个组织中集中控制遥测设置。有关设置应用方式的更多信息,请参阅配置层次结构

托管设置文件位于:

  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux: /etc/claude-code/managed-settings.json

托管设置配置示例:

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

托管设置可以通过 MDM(移动设备管理)或其他设备管理解决方案进行分发。托管设置文件中定义的环境变量具有较高的优先级,用户无法覆盖。

配置详情

常用配置变量

环境变量描述示例值
CLAUDE_CODE_ENABLE_TELEMETRY启用遥测收集(必需)1
OTEL_METRICS_EXPORTER要使用的导出器类型(逗号分隔)console, otlp, prometheus
OTEL_EXPORTER_OTLP_PROTOCOLOTLP 导出器的协议grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTOTLP 收集器端点http://localhost:4317
OTEL_EXPORTER_OTLP_HEADERSOTLP 的认证头Authorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEYmTLS 认证的客户端密钥客户端密钥文件路径
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATEmTLS 认证的客户端证书客户端证书文件路径
OTEL_METRIC_EXPORT_INTERVAL导出间隔(毫秒,默认:10000)5000, 60000

指标基数控制

以下环境变量控制指标中包含哪些属性,以管理基数:

环境变量描述默认值禁用示例
OTEL_METRICS_INCLUDE_SESSION_ID在指标中包含 session.id 属性truefalse
OTEL_METRICS_INCLUDE_VERSION在指标中包含 app.version 属性falsetrue
OTEL_METRICS_INCLUDE_ACCOUNT_UUID在指标中包含 user.account_uuid 属性truefalse

这些变量有助于控制指标的基数,这会影响指标后端的存储需求和查询性能。较低的基数通常意味着更好的性能和更低的存储成本,但分析数据的粒度较低。

配置示例

# 控制台调试(1秒间隔)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

# 多个导出器
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

可用指标

Claude Code 导出以下指标:

指标名称描述单位
claude_code.session.count启动的 CLI 会话计数count
claude_code.lines_of_code.count修改的代码行数count
claude_code.pull_request.count创建的拉取请求数量count
claude_code.commit.count创建的 git 提交数量count
claude_code.cost.usageClaude Code 会话的成本USD
claude_code.token.usage使用的令牌数量tokens

指标详情

所有指标共享这些标准属性:

  • session.id:唯一会话标识符(由 OTEL_METRICS_INCLUDE_SESSION_ID 控制)
  • app.version:当前 Claude Code 版本(由 OTEL_METRICS_INCLUDE_VERSION 控制)
  • organization.id:组织 UUID(已认证时)
  • user.account_uuid:账户 UUID(已认证时,由 OTEL_METRICS_INCLUDE_ACCOUNT_UUID 控制)

1. 会话计数器

在每个会话开始时发出。

2. 代码行计数器

在添加或删除代码时发出。

  • 附加属性:type"added""removed"

3. 拉取请求计数器

通过 Claude Code 创建拉取请求时发出。

4. 提交计数器

通过 Claude Code 创建 git 提交时发出。

5. 成本计数器

在每个 API 请求后发出。

  • 附加属性:model

6. 令牌计数器

在每个 API 请求后发出。

  • 附加属性:type"input""output""cacheRead""cacheCreation")和 model

解读指标数据

这些指标提供了使用模式、生产力和成本的洞察:

使用监控

指标分析机会
claude_code.token.usagetype(输入/输出)、用户、团队或模型细分
claude_code.session.count随时间跟踪采用和参与情况
claude_code.lines_of_code.count通过跟踪代码添加/删除来衡量生产力
claude_code.commit.countclaude_code.pull_request.count了解对开发工作流的影响

成本监控

claude_code.cost.usage 指标有助于:

  • 跟踪团队或个人的使用趋势
  • 识别需要优化的高使用量会话

成本指标是近似值。有关官方计费数据,请参考您的 API 提供商(Anthropic Console、AWS Bedrock 或 Google Cloud Vertex)。

告警和分段

需要考虑的常见告警:

  • 成本突增
  • 异常令牌消耗
  • 特定用户的高会话量

所有指标都可以按 user.account_uuidorganization.idsession.idmodelapp.version 进行分段。

后端考虑因素

后端类型最适合
时间序列数据库(Prometheus)速率计算、聚合指标
列式存储(ClickHouse)复杂查询、唯一用户分析
可观测性平台(Honeycomb、Datadog)高级查询、可视化、告警

对于 DAU/WAU/MAU 指标,选择支持高效唯一值查询的后端。

服务信息

所有指标都导出有:

  • 服务名称:claude-code
  • 服务版本:当前 Claude Code 版本
  • 计量器名称:com.anthropic.claude_code

安全考虑因素

  • 遥测是选择性加入的,需要明确配置
  • 敏感信息(如 API 密钥或文件内容)永远不会包含在指标中