Claude Code 内置 OpenTelemetry（OTel）支持，可将用量数据、成本、工具活动等遥测数据导出到 Prometheus、Grafana、Datadog 等任意兼容 OTel 的监控后端。
六步快速启动
bash
# 第一步：启用遥测
export CLAUDE_CODE_ENABLE_TELEMETRY=1
# 第二步：选择导出器（按需配置）
export OTEL_METRICS_EXPORTER=otlp # otlp / prometheus / console
export OTEL_LOGS_EXPORTER=otlp # otlp / console
# 第三步：配置 OTLP 端点
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
# 第四步：认证（如需要）
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"
# 第五步（调试用）：缩短导出间隔
export OTEL_METRIC_EXPORT_INTERVAL=10000 # 默认 60000ms
export OTEL_LOGS_EXPORT_INTERVAL=5000 # 默认 5000ms
# 第六步：启动 Claude Code
claude调试完成后记得将导出间隔恢复为生产值（指标 60s、日志 5s）。
管理员集中配置（托管设置）
json
{
"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"
}
}可通过 MDM 下发到所有设备，用户无法覆盖。
全部配置环境变量
核心配置
| 变量 | 说明 | 示例值 |
|---|---|---|
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 Collector 端点 | http://localhost:4317 |
OTEL_EXPORTER_OTLP_HEADERS | OTLP 认证头 | Authorization=Bearer token |
OTEL_METRIC_EXPORT_INTERVAL | 指标导出间隔（默认 60000ms） | 5000、60000 |
OTEL_LOGS_EXPORT_INTERVAL | 日志导出间隔（默认 5000ms） | 1000、10000 |
隐私与基数控制
bash
# 隐私相关（默认禁用，启用前评估影响）
export OTEL_LOG_USER_PROMPTS=1 # 记录用户提示词内容
export OTEL_LOG_TOOL_DETAILS=1 # 记录 MCP 工具名和 Skill 名
# 基数控制（影响存储成本）
export OTEL_METRICS_INCLUDE_SESSION_ID=false # 默认 true
export OTEL_METRICS_INCLUDE_ACCOUNT_UUID=false # 默认 true
export OTEL_METRICS_INCLUDE_VERSION=true # 默认 false独立信号端点（覆盖通用配置）
bash
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:4318/v1/metrics
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:4317
# mTLS 认证
export OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY=/path/to/client.key
export OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE=/path/to/client.crt8 类可用指标
| 指标名 | 类型 | 说明 |
|---|---|---|
claude_code.session.count | Counter | 已启动的会话数 |
claude_code.lines_of_code.count | Counter | 已接受的代码行数 |
claude_code.pull_request.count | Counter | 已创建的 PR 数 |
claude_code.commit.count | Counter | 已创建的 Commit 数 |
claude_code.cost.usage | Counter | API 费用（美元） |
claude_code.token.usage | Counter | Token 用量（输入/输出/缓存分类） |
claude_code.code_edit_tool.decision.count | Counter | 代码编辑决策数（接受/拒绝） |
claude_code.active_time | Counter | 用户活跃时间（秒） |
Token 分类属性：input、output、cache_read、cache_creation
代码编辑决策属性：accept（接受）、reject（拒绝）
标准属性（所有指标共有）：
session.id, user.account_uuid, app.version, os.type, runtime.name
5 类事件
| 事件名 | 触发时机 | 关键字段 |
|---|---|---|
user.prompt | 用户发送消息时 | message_length、is_first_in_session |
tool.result | 工具执行完成后 | tool_name、exit_code、duration_ms |
api.request | 发起 API 请求时 | model、request_id、input_tokens |
api.error | API 请求失败时 | error_type、http_status_code |
tool.decision | 工具权限决策时 | tool_name、decision（allow/deny/ask） |
事件关联属性（跨事件追踪）：
session.id 关联同一会话
conversation.id 关联同一对话轮次
request.id 关联一次 API 请求及后续工具调用
动态 Headers（企业认证）
json
// settings.json
{ "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh" }bash
#!/bin/bash
echo "{\"Authorization\": \"Bearer $(get-jwt-token.sh)\", \"X-Org-ID\": \"my-org\"}"默认每 29 分钟刷新（CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS=1740000）。
实用监控示例
Grafana 成本告警
yaml
# 日成本超过 $50 触发告警
- alert: HighClaudeCodeCost
expr: increase(claude_code_cost_usage_total[24h]) > 50
labels:
severity: warningAmazon Bedrock 额外监控
通过 Bedrock 访问时，在 AWS CloudWatch 的 AWS/Bedrock 命名空间下还可查看调用次数和 Token 用量。
原文：Monitoring - Claude Code Docs | 来源：Anthropic 官方文档