返回资讯中心
外部精选
软件工程
#开发者实时流

agent-otel-kit 发布:用一条 docker compose 命令为 Claude Code、Codex 和 Gemini CLI 搭建 OpenTelemetry 仪表盘

来源标题:Show HN: Agent-Otel-Kit – OTel Dashboards for Claude Code, Codex and Gemini CLI

agent-otel-kit 是一个本地 OpenTelemetry 栈,用户执行一次 docker compose up 即可在本机查看 Claude Code、Codex 和 Gemini CLI 的费用、token、工具调用和 trace。它包含接收 OTLP 遥测的 Collector,以及 Prometheus、Loki、Tempo,并在 Grafana 和 Perses 中提供三套相同的仪表盘。另附 Go CLI,可把各 agent 指向 Collector 并用 doctor 命令检查数据是否到达;所有端口仅绑定 127.0.0.1。

Hacker News 最新s3onghyun2026/11/16 · 今天30 分钟阅读

以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。

用一次 docker compose up,就能在本机查看 Claude Code、Codex 和 Gemini CLI 的成本、token、工具调用和追踪。

agent-otel-kit 是一套为 AI 编程助手准备的本地 OpenTelemetry 技术栈:一个 OpenTelemetry Collector,用来接收这些 agent 发来的 OTLP 遥测数据;Prometheus 负责指标,Loki 负责事件,Tempo 负责追踪;Grafana 和 Perses 中各有一套相同的三个仪表盘。另有一个小型 Go CLI,用来把每个 agent 指向这个 collector,并检查数据是否到达。

环境要求:装有 compose 插件的 Docker,以及该 CLI(见「安装 CLI」)。

git clone https://github.com/s3onghyun/agent-otel-kit && cd agent-otel-kit docker compose up -d # 或:make up

brew install s3onghyun/tap/agent-otel-kit # 或用发布归档、go install,或 make build agent-otel-kit setup claude # 或 codex、gemini、all

新开一个 agent 会话并使用一分钟,然后:

agent-otel-kit doctor

打开 http://localhost:3000 上的 Grafana(匿名只读访问;仪表盘位于「Agent OTel Kit」文件夹)。要用 Perses,运行 docker compose --profile perses up -d,然后打开 http://localhost:8080。

所有端口都绑定在 127.0.0.1 上。collector 监听 localhost:4318(OTLP/HTTP)和 localhost:4317(OTLP/gRPC)。

Homebrew(macOS、Linux):brew install s3onghyun/tap/agent-otel-kit 适用于 Linux 和 macOS(amd64、arm64)的预编译归档,附带 checksums.txt:Releases Go 1.24+:go install github.com/s3onghyun/agent-otel-kit/cmd/agent-otel-kit@latest 在克隆目录中:make build 会生成 bin/agent-otel-kit agent-otel-kit version 会打印版本、提交和构建日期。

采集内容:每个 agent 在开启遥测后导出的指标、事件和追踪:成本(仅 Claude Code)、按类型统计的 token 数、会话数、活跃时长、工具调用(含名称、是否成功、时长和权限决定)、模型请求时长,以及每个提示、模型请求和工具调用的追踪 span。

其他标识符保留:session.id(Codex 为 conversation.id)、user.account_uuid、organization.id、Codex 的 user.account_id、installation.id、terminal.type、主机名和操作系统。一切都留在你的机器上;技术栈中没有任何组件会把数据发送到别处(Grafana 和 Loki 的使用情况上报已关闭)。

setup 只修改 agent 自己的用户配置文件。首次运行会把原始文件保存到 ~/.agent-otel-kit/backups/ 下;setup --undo <agent> 会恢复原始文件的精确字节和权限,或删除 setup 创建的文件(及其所在目录)。如果你在 setup 之后又编辑过该文件,undo 会拒绝执行,除非传入 --force。--dry-run 只打印结果而不写入。--endpoint 可把 agent 指向别处的 collector(默认 http://localhost:4318)。

带注释的设置文件不会被修改(setup 会报错停止);这种情况下请手动添加配置块。

只运行过非交互模式以及所列的认证方式。使用个人 Google 登录的 Gemini CLI 被 Google 拒绝用于此客户端("no longer supported for Gemini Code Assist for individuals"),因此该路径是用 AI Studio API key 测试的。

Claude Code、Codex 和 Gemini CLI 默认以 delta 时序导出计数器(每次导出只包含自上次以来的增量),而 Prometheus 只存储累积计数器,因此单纯的 OTLP 到 Prometheus 路径会丢弃或误读它们。collector 的 delta_to_cumulative processor 会在 Prometheus exporter 之前按序列维护累计总值,从而让各 agent 保持默认设置。

compose.yaml 中还有两项相关的 Prometheus 设置:created-timestamp-zero-ingestion 会在序列开始时插入一个零样本,使短会话的首次导出也能被计入;promql-extended-range-selectors 启用 increase(x[$__range] anchored),仪表盘用它来获得精确总量,避免 increase() 的外推。

这三套仪表盘在 Grafana(grafana/dashboards/)和 Perses(perses/provisioning/dashboards/)中都存在。两者都由 tools/gendashboards 中的同一份面板列表生成(make dashboards);如果提交的 JSON 与生成结果不一致,CI 会失败。

Agent 成本与 token:所选时间范围内的成本、token、会话数和活跃时长;按模型分组的各时间区间成本;按类型分组的各时间区间 token;按模型分组的成本;按 agent、模型和类型分组的 token;成本最高的会话。

Agent 工具调用:调用次数、失败数、成功率和 p95 时长;各时间区间的调用次数以及按工具分组的 p95 时长;按工具统计的表格;权限决定(每次调用由谁批准);来自 Loki 的失败调用。工具指标 agent_otel_kit.tool.duration 由 collector 中的 signal_to_metrics connector 根据每个 agent 的工具结果事件构建,因此对所有 agent 都一致。

Agent 会话与追踪:各会话的成本和 token、来自 Tempo 的交互追踪、追踪瀑布图(把 trace ID 粘贴到 Trace ID 框中)、模型请求时长、按类型分组的事件速率,以及所选会话的事件流。

每个标签都会归一化为 agent_name(claude-code、codex、gemini-cli),取值来自各 agent 设置的 service.name。在 agent 上设置 OTEL_RESOURCE_ATTRIBUTES=agent.name=<name> 可覆盖它。Claude Code 自带的 agent.name 属性(子 agent 名称)和 Codex 的 agent_name 属性(agent 路径,主 agent 为 /root)会保留为 subagent.name。Codex 的 conversation.id 会复制到 session.id,其 token_type 复制到 type。

Token 总量(Tokens 统计项和按会话的 Tokens 列)只累加不重叠的 token 类型:Codex 把缓存输入计入 input、把推理计入 output,Gemini CLI 把缓存计入 input,因此这些部分(以及 Codex 的 total)不会重复累加。Claude Code 的 cacheRead 和 cacheCreation 与 input 相互独立,会被累加。按类型的明细会显示所有类型,包括重叠的类型。

仪表盘上可见的 agent 差异:

(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →