使用 OpenTelemetry 监控 Cline:令牌用量与成本
Cline 是一个面向 VS Code 的开源 AI 编程 agent,能够规划并执行多步骤任务:读取文件、修改代码、运行 shell 命令、调用 MCP 服务器。Cline 自带的账户页面只能看到总花费,却看不出钱花在了哪里——用了哪个模型、在哪个仓库、是哪位开发者,以及每次请求中有多少 token 其实是重复发送的上下文而非新任务。
Cline 在 VS Code 扩展中内置了 OpenTelemetry 导出器,无需额外插件或封装。它以 cline 作为 service name 上报事件和指标。通过在 SigNoz 中监控 Cline,你可以查看按模型和开发者拆分的 token 用量与费用、prompt cache 的命中率、agent 调用了哪些工具、哪些调用失败、请求延迟和首 token 时间,以及每一条 provider API 错误及其详细信息。
前提条件
- SigNoz 环境(二选一):
- 拥有有效 ingestion key 的 SigNoz Cloud 账户
- 自托管(Self-Hosted)的 SigNoz 实例
- 已安装 Cline 扩展 的 VS Code(v4.1.16 及以上版本)
- 已在 Cline 中配置好模型 provider
用 OpenTelemetry 监控 Cline
Cline 在扩展激活时从 CLINE_OTEL_* 环境变量读取导出器配置,所以整个配置过程就是设置环境变量再重启,不依赖任何 Cline 账户套餐。
第 1 步:在 shell 中导出以下配置。
Copy# 必须设置。默认 bundle 不会输出任何 task 事件或指标。
export CLINE_BUNDLE_OVERRIDE=legacy
export CLINE_OTEL_TELEMETRY_ENABLED=true
export CLINE_OTEL_METRICS_EXPORTER=otlp
export CLINE_OTEL_LOGS_EXPORTER=otlp
export CLINE_OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export CLINE_OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export CLINE_OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
请确认以下取值:
<region>:你的 SigNoz Cloud region。<your-ingestion-key>:您的 SigNoz 摄取密钥。
Cline 的 gRPC 导出器将认证头作为 headers 传递,而不是 gRPC metadata,因此 OpenTelemetry SDK 会忽略它们,导致所有导出请求都被拒绝并返回 16 UNAUTHENTICATED: Invalid or missing key。由于 gRPC 是文档中推荐的默认协议,这是配置失败的最常见原因。在需要认证的任意后端中,请使用 http/protobuf。
该扩展包含两个内部 bundle。在默认的 next bundle 中,任务执行通过一个 SDK 层运行,其遥测数据无法到达扩展的 OpenTelemetry provider,因此不会生成任何任务事件或指标。如果未设置 CLINE_BUNDLE_OVERRIDE=legacy,您只会看到少量扩展生命周期事件成功到达,除此之外别无其他。这看起来像是管道在工作但没有使用量。
步骤 2:从该 shell 启动 VS Code。
复制code
扩展宿主继承 VS Code 进程的环境变量,因此从 Finder、Dock 或开始菜单快捷方式启动 VS Code 不会继承任何环境变量。若要使配置永久生效,请将这些 export 语句添加到您的 shell 配置文件中,并始终通过终端启动 VS Code;或者通过您的 MDM 或工作区工具进行设置。
步骤 3:在 Cline 中发送一个使用工具的提示,例如让它读取并编辑一个文件。
Cline 在激活时仅读取一次配置,因此修改这些变量需要完全重启 VS Code,而不仅仅是重新加载窗口。
使用自托管 SigNoz?大多数步骤相同。若要调整本指南,请更新端点并移除摄取密钥头,具体操作参见云端到自托管。
在 SigNoz 中查看 Cline 日志
Cline 通过 OpenTelemetry 日志协议导出事件,而非 trace。在第一个提示发出后等待几秒钟,然后打开日志资源管理器并筛选 service.name = 'cline'。

点开一条记录即可查看其属性。task.tokens 事件包含一次模型请求的 token 数量和计算出的费用。

在 SigNoz 中查看 Cline 指标
除了事件之外,Cline 还会以相同的服务名发布一组 cline.* 指标。打开 Metrics Explorer,搜索 cline,并按 model 分组,即可按模型拆分查看这些指标。

| 指标 | 类型 | 含义 |
|---|---|---|
cline.tokens.input.total、cline.tokens.output.total | Counter | 累计的提示词和补全 token 数 |
cline.tokens.input.per_response、cline.tokens.output.per_response | Histogram | 每次模型响应的 token 分布 |
cline.cache.read.tokens.total、cline.cache.write.tokens.total | Counter | 提示词缓存的读取和写入 |
cline.cache.read.tokens.per_event、cline.cache.write.tokens.per_event | Histogram | 每次请求的缓存读写量 |
cline.cost.total | Counter | 累计成本(美元) |
cline.cost.per_event | 直方图 | 每个请求的成本分布 |
cline.api.duration.seconds | 直方图 | 模型请求完整耗时 |
cline.api.ttft.seconds | 直方图 | 首词元延迟 |
cline.tool.calls.total, cline.tool.calls.per_task | 计数器, 直方图 | 工具调用次数及单任务调用量 |
cline.turns.total, cline.turns.per_task | 计数器, 直方图 | 模型往返次数及单任务往返量 |
cline.ai_output.accepted.lines_added.total, lines_changed.total, lines_deleted.total | 计数器 | 已接受 AI 输出的增/改/删行数 |
每个指标均附带 model、provider、extension_variant 和 ulid 标签,因此在此处也可像事件一样按模型或任务维度拆解。直方图在 SigNoz 中会生成五个序列(.bucket、.count、.sum、.min、.max),构建百分位面板时应搜索 cline.api.ttft.seconds.bucket,而非基础指标名。
该扩展仅集成 OpenTelemetry 日志与指标 SDK,不含 Trace SDK 或 Trace 导出器,因此没有瀑布图,任何记录也不含 Trace 或 Span ID。请使用 ulid 标签来聚合属于同一任务的所有事件。
需了解的标签属性
事件名作为日志正文而非标签属性传输,因此查询时需使用 body = 'task.tokens' 而非名称字段过滤。另有四处细节决定查询是否正确。
ulid是任务关联键。 同一任务产生的所有事件共享该值。由于 Cline 不输出 Trace,无法通过 Trace 或 Span ID 分组,ulid是重构任务上下文的唯一依据。- 缓存读取量单独统计,不计入输入量。
cacheReadTokens未包含在tokensIn中。两者相加会导致上下文重复计数。 - 模型字段名不统一。
task.tokens和task.conversation_turn用的是model,而task.tool_used用的是modelId。如果按 token 事件写过滤条件,工具事件会被全部漏掉。 - 缺失值以字符串
"undefined"的形式出现。requestId、errorStatus和isNativeToolCall缺失时不是直接省略,而是写入字面文本,所以过滤时需要显式排除这个字符串。
值得利用的事件包括:task.tokens(tokensIn、tokensOut、cacheReadTokens、cacheWriteTokens、totalCost、model、provider)、task.tool_used(tool、success、autoApproved)、task.conversation_turn(mode、source)以及 task.provider_api_error(errorType、errorClass、errorMessage、failurePhase)。
追踪 Token 用量与成本
成本是大多数团队给编码 agent 做埋点的首要原因,而 Cline 在 task.tokens 事件中按每次模型请求上报成本。在基于这个数字做开发之前,有两点需要了解。
成本是在客户端计算的。 Cline 用自己的分模型价格表乘以 token 数量,而不是从 provider 那里读取实际金额。这意味着对你免费的模型(包括 Cline 自带的内置 provider),totalCost 会显示 0,而且这个零在算术上是正确的,并非导出出了问题。想要有意义的成本数据,需要在 Settings > API Provider 下配置一个明确定价的 provider。
大部分输入 token 其实是重发的上下文。 Cline 每一轮都会重新发送系统提示词和工作区上下文,哪怕提示词只有一个词,也可能带上八千个输入 token。要把 cacheReadTokens 和 tokensIn 对照着看:缓存读取量接近输入总量,说明 provider 的缓存正在消化这些重复内容;数值偏低,则意味着你每一轮都在为重复内容付全价。
这两类数据都能直接从事件中干净地聚合出来,所以 token 或成本面板从第一个任务开始就是准确的:
