2025年5月15日作者 D.Sheep 0

Claude Code 使用监控

通过 OpenTelemetry 指标监控 Claude Code 的使用情况

OpenTelemetry 支持目前处于测试阶段，细节可能会有变动。

Claude Code 中的 OpenTelemetry

Claude Code 支持 OpenTelemetry (OTel) 指标，用于监控与可观测性。本文介绍如何启用并配置 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. 调试用：降低导出间隔（默认10分钟=600000ms）
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_PROTOCOL	OTLP 导出协议	grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP 收集端点	http://localhost:4317
OTEL_EXPORTER_OTLP_HEADERS	OTLP 认证头	Authorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY	mTLS 客户端密钥路径	密钥文件路径
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE	mTLS 客户端证书路径	证书文件路径
OTEL_METRIC_EXPORT_INTERVAL	导出间隔（毫秒，默认10000）	5000, 60000

指标基数控制

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

环境变量	描述	默认值	关闭示例
OTEL_METRICS_INCLUDE_SESSION_ID	指标中包含 session.id 属性	true	false
OTEL_METRICS_INCLUDE_VERSION	指标中包含 app.version 属性	false	true
OTEL_METRICS_INCLUDE_ACCOUNT_UUID	指标中包含 user.account_uuid 属性	true	false

这些变量有助于控制基数，从而影响指标存储与查询性能。基数越低，性能越好、存储成本越低，但数据颗粒度减少。

配置示例

# 控制台调试（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	创建的 PR 数量	count
claude_code.commit.count	创建的 git commit 数量	count
claude_code.cost.usage	会话费用	USD
claude_code.token.usage	使用的 token 数量	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 控制）

具体说明：

会话计数器：每次会话开始时发送
代码行计数器：代码增删时发送，附加属性 type（“added” 或 “removed”）
PR 计数器：创建 PR 时发送
Commit 计数器：创建 git commit 时发送
费用计数器：每次 API 请求后发送，附加属性 model
Token 计数器：每次 API 请求后发送，附加属性 type（“input”、“output”、“cacheRead”、“cacheCreation”）和 model

指标数据解读

这些指标有助于洞察使用模式、生产力和成本：

使用监控
- claude_code.token.usage：按类型（输入/输出）、用户、团队或模型拆解
- claude_code.session.count：跟踪用户采纳与活跃度
- claude_code.lines_of_code.count：通过代码增删量衡量生产力
- claude_code.commit.count & claude_code.pull_request.count：理解对开发流程的影响
成本监控
- claude_code.cost.usage：跟踪团队/个人用量趋势，识别高用量会话以便优化（成本为预估值，官方账单请以 API 提供方为准，如 Anthropic 控制台、AWS Bedrock、Google Cloud Vertex）
告警与分段
- 可针对成本飙升、异常 token 消耗、特定用户高会话量等设置告警
- 所有指标可按 user.account_uuid、organization.id、session.id、model、app.version 分段

后端建议

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

如需统计 DAU/WAU/MAU，请选用支持高效唯一值查询的后端。

服务信息

所有指标都会带上：

Service Name: claude-code
Service Version: 当前 Claude Code 版本
Meter Name: com.anthropic.claude_code

安全说明

遥测为可选，需显式配置
指标中不会包含敏感信息（如 API 密钥或文件内容）

分类目录Claude Code 101 Claude Max 拼车