​

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

有关完整配置选项，请参阅 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"
  }
}

​

配置详情

​

常用配置变量

​

指标基数控制

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

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

​

配置示例

# 控制台调试（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 导出以下指标：

​

指标详情

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

• 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.cost.usage 指标有助于：

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

​

告警和分段

需要考虑的常见告警：

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

所有指标都可以按 user.account_uuid、organization.id、session.id、model 和 app.version 进行分段。

​

后端考虑因素

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

​

服务信息

所有指标都导出有：

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

​

安全考虑因素

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