监控使用情况（OpenTelemetry）

通过 OpenTelemetry（OTel）导出遥测数据，跨组织追踪 Claude Code 使用情况、成本和工具活动。Claude Code 通过标准指标协议导出时间序列数据，通过日志/事件协议导出事件。

快速开始

通过环境变量配置 OpenTelemetry：

# 1. 启用遥测
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. 选择导出器（均为可选）
export OTEL_METRICS_EXPORTER=otlp       # 选项：otlp、prometheus、console
export OTEL_LOGS_EXPORTER=otlp          # 选项：otlp、console

# 3. 配置 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. 调试时缩短导出间隔
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 秒（默认：60000ms）
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 秒（默认：5000ms）

claude

管理员配置

管理员可通过托管设置文件为所有用户集中配置：

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

常用配置变量

环境变量	说明	示例值
CLAUDE_CODE_ENABLE_TELEMETRY	启用遥测收集（必填）	1
OTEL_METRICS_EXPORTER	指标导出器类型（逗号分隔）	console、otlp、prometheus
OTEL_LOGS_EXPORTER	日志/事件导出器类型	console、otlp
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_METRIC_EXPORT_INTERVAL	指标导出间隔（毫秒，默认 60000）	5000
OTEL_LOGS_EXPORT_INTERVAL	日志导出间隔（毫秒，默认 5000）	1000
OTEL_LOG_USER_PROMPTS	启用用户提示内容日志记录（默认禁用）	1
OTEL_LOG_TOOL_DETAILS	在工具事件中记录 MCP/技能名称（默认禁用）	1

基数控制变量

变量	说明	默认值
OTEL_METRICS_INCLUDE_SESSION_ID	在指标中包含 session.id 属性	true
OTEL_METRICS_INCLUDE_VERSION	在指标中包含 app.version 属性	false
OTEL_METRICS_INCLUDE_ACCOUNT_UUID	在指标中包含账户 UUID	true

可用指标

标准属性

所有指标和事件共享：session.id、app.version、organization.id、user.account_uuid、user.account_id、user.id、user.email、terminal.type

指标列表

指标名称	说明	单位
claude_code.session.count	启动的 CLI 会话数	count
claude_code.lines_of_code.count	修改的代码行数	count
claude_code.pull_request.count	创建的 Pull Request 数	count
claude_code.commit.count	创建的 Git 提交数	count
claude_code.cost.usage	会话成本	USD
claude_code.token.usage	使用的 Token 数量	tokens
claude_code.code_edit_tool.decision	代码编辑工具权限决策数	count
claude_code.active_time.total	总活跃时间	s

指标详情

代码行计数器追加属性：type（"added" 或 "removed"）

成本计数器追加属性：model（如 "claude-sonnet-4-6"）

Token 计数器追加属性：type（"input"、"output"、"cacheRead"、"cacheCreation"）和 model

代码编辑工具决策计数器追加属性：tool_name、decision（"accept" 或 "reject"）、source、language

可用事件

启用 OTEL_LOGS_EXPORTER 后导出：

事件关联属性

prompt.id：UUID v4 标识符，关联处理单个用户提示时产生的所有事件。

事件类型

事件名称	触发时机
claude_code.user_prompt	用户提交提示时
claude_code.tool_result	工具完成执行时
claude_code.api_request	发送 API 请求时
claude_code.api_error	API 请求失败时
claude_code.tool_decision	做出工具权限决策时

工具结果事件包含：tool_name、success、duration_ms、error、decision_type、decision_source、tool_result_size_bytes

API 请求事件包含：model、cost_usd、duration_ms、input_tokens、output_tokens、cache_read_tokens、cache_creation_tokens、speed（"fast" 或 "normal"）

使用示例配置

# 控制台调试（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=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

多团队支持

使用 OTEL_RESOURCE_ATTRIBUTES 添加自定义属性以区分不同团队：

export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

格式要求：使用逗号分隔的 key=value 对，不允许空格。org.name=My Company 无效，应使用 org.name=My_Company。

动态 Headers

对于需要动态认证的企业环境，配置脚本动态生成 Headers：

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

脚本必须输出有效的 JSON：

#!/bin/bash
echo "{\"Authorization\": \"Bearer $(get-token.sh)\"}"

默认每 29 分钟刷新一次，可通过 CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS 自定义。

安全和隐私

• 遥测是选择加入的，需要显式配置
• 不包含原始文件内容和代码片段
• 工具执行事件的 tool_parameters 字段中可能包含 Bash 命令和文件路径
• 默认不收集用户提示内容（只记录提示长度）
• MCP 服务器/工具名称和技能名称默认不记录

相关资源

• 分析仪表板：团队级使用指标和贡献指标
• 管理成本：设置花费限制并优化 Token 使用
• ROI 测量指南：完整的 Docker Compose 配置和生产力报告模板