我如何使用 OTEL、Prometheus 和 Grafana 为 Claude Code Metrics 构建实时仪表盘

Source: Dev.to

请提供您希望翻译的完整文本（包括正文、标题、段落等），我将在保持原有 Markdown 格式、代码块和 URL 不变的前提下，将内容翻译成简体中文。谢谢！

概述

我想要 Claude Code 的具体数据——tokens、cost、lines of code、productivity ratios、ROI。本指南展示了如何使用 OTEL 收集遥测数据，将其存储在 Prometheus 中，并在 Grafana 中进行可视化。

先决条件

• Claude Code 已启用原生 OTEL 遥测
• Prometheus（推荐使用 v2.45 以上）
• Grafana（推荐使用 v10 以上）
• jq 用于 JSON 解析（可选，用于验证）

1. 在 Claude Code 中启用遥测

将以下环境变量添加到你的 shell 配置文件（~/.zshrc、~/.bashrc 等）中：

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:9090/api/v1/otlp

编辑完成后，重新加载配置文件：

source ~/.zshrc   # or source ~/.bashrc

2. 配置 Prometheus 接收 OTLP 指标

Prometheus 必须在启用 OTLP 接收器并使用 delta‑to‑cumulative 转换标志的情况下启动：

prometheus \
  --config.file=prometheus.yml \
  --web.enable-otlp-receiver \
  --enable-feature=otlp-deltatocumulative

注意： 在 macOS 使用 Homebrew 时，可能需要编辑服务的 plist 或将该命令包装在脚本中，以包含这些标志。

为什么使用 otlp-deltatocumulative？

某些 Claude Code 指标（例如代码行数）是 delta 指标。该标志会自动将它们转换为累计计数器，这是 Prometheus 所期望的。

3. 验证数据摄取

运行以下命令列出 Prometheus 已接收的指标名称：

curl 'http://localhost:9090/api/v1/label/__name__/values' | jq '.data[]' | grep claude

您应该会看到类似的指标：

• claude_code_token_usage_tokens_total
• claude_code_cost_usage_USD_total
• claude_code_active_time_seconds_total
• claude_code_lines_of_code_count_total
• claude_code_session_count_total

4. 指标参考

解释 active_time

• type="cli" – Claude 处理的时长。
• type="user" – 您交互的时长。

生产力乘数 为 cli time / user time。

5. Grafana 仪表板

我创建了三个仪表板：

1. Claude Code Metrics – 令牌统计、成本细分、生产率比率。
2. Daily/Weekly Summary – 聚合统计，具备时间范围感知。
3. Engineering Economics – ROI 计算、团队等价、业务指标。

Importing

将 JSON 文件导出到 GitHub gist（链接待定），然后在 Grafana 中通过 Dashboards → Import 导入。

6. Grafana 变量与实用查询

定义变量：

• Hourly rate – 用于 ROI 计算。
• Average developer lines/hour – 用于团队等价。
• Productivity Ratio – CLI time / User time。

示例查询

生产率比率

sum(claude_code_active_time_seconds_total{type="cli"}) 
/
sum(claude_code_active_time_seconds_total{type="user"})

每美元行数

sum(sum_over_time(claude_code_lines_of_code_count_total[$__range]))
/
sum(increase(claude_code_cost_usage_USD_total[$__range]))

等效开发者工时（假设 75 行/小时）

sum(sum_over_time(claude_code_lines_of_code_count_total[$__range])) / 75

最大计划 ROI（针对每月 $200 订阅者）

sum(increase(claude_code_cost_usage_USD_total[$__range])) 
/ (6.67 * ($__range_s / 86400))

处理 Delta 指标

claude_code_lines_of_code_count_total 是一个 delta 指标，因此使用 sum_over_time() 而不是 increase()：

# Incorrect – yields extrapolated values
sum(increase(claude_code_lines_of_code_count_total[$__range]))

# Correct
sum(sum_over_time(claude_code_lines_of_code_count_total[$__range]))

7. 示例输出（1 小时）

• 27,000 行代码
• 11 分钟的用户时间
• 362× 速度倍率
• $47 K 等价产出价值

当运行多个并行代理时，生产率比率峰值超过 10,000×。

8. 导出到其他 OTLP 后端

OTEL 导出器可与任何兼容 OTLP 的端点配合使用。只需更改 endpoint 变量：

export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-backend-endpoint

对于 Datadog，请指向其 OTLP 接收 URL；指标名称保持不变。

9. 未来增强

• 警报 当生产率比率下降时（例如，你卡住了）。
• 成本预测 基于当前的消耗率。
• 比较面板 用于不同项目或团队。

如果你扩展此设置，欢迎分享你的结果！