监控使用情况
使用 OpenTelemetry 指标监控 Claude Code 使用情况
OpenTelemetry 支持目前处于测试阶段,详细信息可能会发生变化。
Claude Code 中的 OpenTelemetry
Claude Code 支持 OpenTelemetry (OTel) 指标用于监控和可观测性。本文档解释了如何为 Claude Code 启用和配置 OTel。
所有指标都是通过 OpenTelemetry 的标准指标协议导出的时间序列数据。用户有责任确保其指标后端配置正确,并且聚合粒度满足其监控要求。
快速开始
使用环境变量配置 OpenTelemetry:
默认导出间隔为 10 分钟。在设置过程中,您可能希望使用较短的间隔进行调试。请记住在生产环境中重置此设置。
有关完整配置选项,请参阅 OpenTelemetry 规范。
管理员配置
管理员可以通过托管设置文件为所有用户配置 OpenTelemetry 设置。这允许在整个组织中集中控制遥测设置。有关设置应用方式的更多信息,请参阅配置层次结构。
托管设置文件位于:
- macOS:
/Library/Application Support/ClaudeCode/managed-settings.json
- Linux:
/etc/claude-code/managed-settings.json
托管设置配置示例:
托管设置可以通过 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 |
这些变量有助于控制指标的基数,这会影响指标后端的存储需求和查询性能。较低的基数通常意味着更好的性能和更低的存储成本,但分析数据的粒度较低。
配置示例
可用指标
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.usage | Claude 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.usage | 按 type (输入/输出)、用户、团队或模型细分 |
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 Console、AWS Bedrock 或 Google Cloud Vertex)。
告警和分段
需要考虑的常见告警:
- 成本突增
- 异常令牌消耗
- 特定用户的高会话量
所有指标都可以按 user.account_uuid
、organization.id
、session.id
、model
和 app.version
进行分段。
后端考虑因素
后端类型 | 最适合 |
---|---|
时间序列数据库(Prometheus) | 速率计算、聚合指标 |
列式存储(ClickHouse) | 复杂查询、唯一用户分析 |
可观测性平台(Honeycomb、Datadog) | 高级查询、可视化、告警 |
对于 DAU/WAU/MAU 指标,选择支持高效唯一值查询的后端。
服务信息
所有指标都导出有:
- 服务名称:
claude-code
- 服务版本:当前 Claude Code 版本
- 计量器名称:
com.anthropic.claude_code
安全考虑因素
- 遥测是选择性加入的,需要明确配置
- 敏感信息(如 API 密钥或文件内容)永远不会包含在指标中