OpenCode Token监控实战：从日志解析到实时速度与缓存命中率

自从 OpenCode 升到 V2 之后我在终端里写代码越来越依赖它但很快就发现一个问题我根本不知道自己这半天到底烧了多少 Token。OpenCode 原生界面里没有实时的 Token 速度、没有成本估算连上下文缓存命中率这种直接影响结算的指标都只能靠猜。于是我花了一晚上写了个配套的小插件读取 OpenCode 的运行日志解析出每次 LLM 调用的 usage 信息在前端页面上实时刷新显示 Token 消耗速度、累计消耗量和缓存命中率。这里把从方案选型到适配 V2 的完整过程梳理一遍给想自己写 OpenCode 辅助工具的同学做个参考。这个插件主要解决三个问题第一OpenCode 执行长任务时缺少 Token 消耗的可视化监控你盯着一个空转的终端窗口心里没底第二V2 版本改动导致旧的日志解析逻辑失效需要一套能自动适配新旧格式的解析层第三需要一种够轻的方式随时查看而不是每次打开一个冗长的统计文件去肉眼找数据。如果你在用 OpenCode 做日常开发、对 token 成本比较敏感或者单纯想了解如何给一个 CLI 类 AI 工具做外围监控这篇都值得看看。1. 为什么偏要给 OpenCode 加一套外部监控1.1 终端里的 Token 消耗是笔糊涂账OpenCode 这个工具的核心体验是在终端里和模型连续对话让它改代码、跑测试、分析报错。它的界面设计倾向于展示对话内容和代码 diff指标信息被压缩到非常有限的位置。我在用 V1 的时候就忍了很久往上翻历史输出偶尔能看到一行 cost但没有持续刷新的概念。跑一个长任务比如让模型批量重构几十个文件可能持续半小时以上这段时间里到底是在高速输出还是卡在思考环节我完全不知道。更麻烦的是成本口径。现在主流模型计费都分 input、output还有 prompt 缓存的独立档位。缓存命中率高了同样一段长上下文能便宜很多命中率低了等于每轮都在为重复的系统提示词付费。OpenCode 的会话通常会把项目结构、最近文件内容、工具调用历史全部塞进上下文这些正是缓存优化最该发挥作用的区域。可官方终端里看不到命中率数字我连自己当前会话处于高缓存收益还是低缓存收益状态都判断不了。所以我的直接需求就是做一个外部监控面板不需要改 OpenCode 本体不依赖官方埋点白天挂着浏览器标签页就能随时瞄一眼。1.2 三个可选方案最后为什么选日志解析给 OpenCode 这类工具做监控摆在面前的路大致有三条。我在动手前把优劣势列过一张表方案侵入性实时性字段完整度主要风险抓取终端输出截图 / tmux / ANSI 解析低高低屏幕输出不含结构化 usage终端文本混入换行和 ANSI 转义解析极其脆弱在 OpenCode 与 API 之间加 HTTP 代理高最高中只能看到请求响应头部字段会接触敏感凭据影响 TLS 信任链解析 OpenCode 日志文件低中高高包含完整 usage 字段日志格式会随版本变化终端输出方案第一个被我否了。OpenCode 是一个全屏 TUI输出里混着大量光标控制字符和渲染刷新序列就算用 tmux pipe-pane 抓出来时间戳和字段结构也完全不可靠。代理方案我没有任何犹豫直接排除在模型 API 之间插一层等于让自己写的脚本碰用户的 API key一旦脚本有 bug密钥泄露风险太不值得。日志解析是最自然的选择OpenCode 本来就会落地写入调试日志里面每次 LLM 调用都有结构化 JSON 记录我只做只读 tail不干预进程风险最小。方案定下来之后剩下的问题就聚焦在两个日志里的字段怎么归一化成统一的指标口径以及怎么把文件流变成页面上的实时数字。这两块分别对应下面两节。2. Token 速度与命中率的口径先得把账算明白2.1 从 usage 字段说起OpenCode 的日志以 JSONL 为主每次 LLM 调用结束都会有一条包含请求元数据和用量数据的记录。我第一次打开日志文件时看到的字段大致有input_tokens、output_tokens、cache_read_input_tokens、cache_creation_input_tokens。听起来很好懂但真正开始写解析器才发现坑不少。最大的坑是不同模型服务商对字段的命名和语义不统一。Anthropic 风格的回复里缓存拆成 cache_creation 和 cache_read 两个字段OpenAI 兼容接口上经常叫 cached_tokens还有些统一网关会把 usage 做成嵌套结构input 内部再带上一次调用是否命中缓存的标记。另外input_tokens这个值在不同服务商那里口径也不一样有的已经包含了缓存命中的部分有的则排除在外。如果不先做归一化后面算命中率时会得到一个完全离谱的数字。我第一版解析函数是这样的# opencode_v2_usage.py import json def parse_usage_line(raw_line: str) - dict | None: try: data json.loads(raw_line) except json.JSONDecodeError: return None # 不同版本的日志事件类型不一样V1 用 typeV2 用 event if data.get(type) not in (usage, llm_call) and data.get(event) ! llm_usage: return None usage data.get(usage) or data.get(tokens) or {} input_tokens int(usage.get(input_tokens) or usage.get(prompt_tokens) or 0) output_tokens int(usage.get(output_tokens) or usage.get(completion_tokens) or 0) cache_read int( usage.get(cache_read_input_tokens) or usage.get(cache_read_tokens) or usage.get(cached_tokens) or 0 ) cache_write int(usage.get(cache_creation_input_tokens) or 0) return { input: input_tokens, output: output_tokens, cache_read: cache_read, cache_write: cache_write, model: data.get(model) or data.get(model_name) or unknown, session: data.get(session_id) or data.get(session, {}).get(id, default), ts: data.get(ts) or data.get(timestamp) or 0, }这里有个经验尽量只读原始字段不要自己去加减。因为你并不知道上游在统计 input 时是否已经把 cache_read 算进去了。我踩过一次某网关返回的 input_tokens 是 5000cache_read 是 3000看起来命中率是 3000/500060%实际上它的语义是未命中缓存的新输入是 5000另外命中了 3000真实命中率应该是 3000/800037.5%。这种差异用代码无法完全排除只能靠统计几个请求后人工校准。2.2 实时速度为什么不能用瞬时值第一次看到速度曲线图时我差点以为写错了。模型输出时经常是一整段瞬间返回可能 15 秒内吐出 18000 个 output token那一个瞬间算出来的速度是 1200 tok/s可下一段是模型在思考、在调工具好几十秒一个 token 都没有瞬时速度直接掉到 0。这种图挂在页面上基本等于心电图完全没法看。所以要的是平滑后的速度我用的是最简单的滑窗均值维护最近 60 秒内所有 usage 事件消耗的 token 总数除以 60 秒。窗口内每 5 秒更新一次可调参数。这个窗口长度是我试过的折中方案——太短的话峰值仍然压不住太长的话又失去实时刷新的意义。speed_tps (input_tokens output_tokens cache_read cache_write) / window_seconds把所有 token 类型都计进去是因为上下文预填充也要花时间。用户关心的其实是模型吞吐的总量而不是单分 output 的快慢。如果你只想看生成速度那就只统计 output面板上我做了两个口径切换默认展示总值。2.3 命中率到底是什么面板上的命中率我明确指的是 LLM 上下文缓存命中率不是代码生成正确率也不是 RAG 检索命中率。它定义成hit_rate cache_read / (cache_read non_cache_input) * 100%这里的 non_cache_input 是真正需要模型重新处理的输入 token。为什么这个指标值得单拎出来看因为缓存命中的 token 计费大概只有不命中的十分之一。对于 OpenCode 这种会把项目结构、文件内容、历史工具调用堆进上下文的工具会话越长context 里重复的前缀越多缓存命中率越值得关注。我自己的经验数值是新开会话前 5 到 10 分钟命中率常常在 20% 以下一旦同一个会话持续跑系统提示词和项目前缀沉淀下来命中率能稳定爬到 70% 以上。这直接决定了同样一轮长对话的成本差出 2 到 3 倍。如果没有实时数字你根本感知不到这种变化很容易在缓存已经养起来之后莫名开一个新会话把优势全部扔掉。3. 实时刷新链路从 tail 日志到页面数字3.1 采集端tail -F 加累加器采集端的核心逻辑特别简单循环读取日志文件的新增内容逐行解析把有效 usage 事件丢进一个全局累加器。为了做滑窗平均我用 collections.deque 保存最近 60 秒内的事件时间戳和 token 值这样每次快照只需要遍历 deque 求和不用记录全量会话数据。# collector.py import time from collections import deque # 全局状态 window_deque deque(maxlen10000) total_input 0 total_output 0 total_cache_read 0 def ingest_event(usage: dict): global total_input, total_output, total_cache_read total_input usage[input] total_output usage[output] total_cache_read usage[cache_read] window_deque.append({ ts: usage[ts], tokens: usage[input] usage[output] usage[cache_read] usage[cache_write], }) def snapshot(): # 清理 60 秒外的旧事件 cutoff time.time() - 60 while window_deque and window_deque[0][ts] cutoff: window_deque.popleft() tokens sum(item[tokens] for item in window_deque) return { speed_tps: tokens / 60 if tokens else 0, total_tokens: total_input total_output total_cache_read, hit_rate: _hit_rate(), }这个脚本用tail -F的方式打开日志文件。-F会自动处理文件轮转这对 V2 的场景很重要因为 V2 的日志可能按会话归档主日志文件会被重命名。Python 里我直接用循环读行遇到 EOF 就 sleep 0.2 秒继续等而不是真去调用系统 tail这样能减少一个外部进程依赖。3.2 SSE 推送而不是 WebSocket数据从采集端到浏览器我选了 Server-Sent Events。理由很实在这是一个纯单向推送场景SSE 走普通 HTTP浏览器原生支持 EventSource断线还能自动重连。WebSocket 能做到的双向能力在这里用不上反而要自己处理心跳和连接状态完全是给自己加戏。服务端我用 FastAPI 写了十几行代码# server.py import json import asyncio from fastapi import FastAPI from fastapi.responses import StreamingResponse app FastAPI() app.get(/metrics/stream) async def metrics_stream(): async def gen(): while True: # 注意这里对每个连接都构建一份 payload data json.dumps(snapshot()) yield fdata: {data}\n\n await asyncio.sleep(5) return StreamingResponse(gen(), media_typetext/event-stream)一个小细节sse 流必须设置 media_type 为text/event-stream否则前端 EventSource 不会触发 onmessage。另外每个连接都是独立的异步生成器多开一个标签页就会多一个读队列好在这点负载可以忽略。3.3 前端展示一个不引框架的 Dashboard页面这部分我不想引入任何前端框架一个 HTML 加几十行 JavaScript 就够。核心指标用卡片形式铺开实时数据通过 EventSource 接住后直接改 DOM 文本。div classmetric-card div classmetric-title当前 Token 速度/div div classmetric-value idspeed--/div div classmetric-unittok/s/div /div div classmetric-card div classmetric-title缓存命中率/div div classmetric-value idhit--/div div classmetric-unit%/div /div div classmetric-card div classmetric-title累计消耗/div div classmetric-value idtotal--/div div classmetric-unittokens/div /divconst es new EventSource(/metrics/stream); es.onmessage (e) { const m JSON.parse(e.data); document.getElementById(speed).textContent m.speed_tps.toFixed(1); document.getElementById(hit).textContent m.hit_rate.toFixed(1); document.getElementById(total).textContent m.total_tokens.toLocaleString(); };页面上的指标口径我整理成了一张表避免以后自己看懵指标单位展示口径当前 Token 速度tok/s60 秒滑窗内 token 总量 / 60累计消耗 Tokentokens采集进程启动后所有 usage 之和缓存命中率%cache_read / (cache_read non_cache_input)当前模型string最后一次 usage 事件的 model 字段会话 IDstring当前聚合的 session id可切换前端遇到 SSE 断线重连时我会先拉一次/metrics/summary接口把累计值校准一下避免只靠增量推送导致页面数值和真实值越差越多。这是从实际使用里学到的浏览器标签页挂久了EventSource 一旦重连中间丢掉的几帧数据会让 total 永久偏小。4. 适配 V2这次升级到底改了多少东西4.1 日志路径和轮转方式变了V1 时期日志文件的路径是固定的每天一个文件路径不会变化tail -F 一挂就是一天。V2 升级之后我照常启动采集器结果页面上一片空白检查发现日志文件路径变了V2 不再把内容写在原来的全局文件里而是按会话归档到独立目录。我现在的处理方式比较务实启动时扫描日志目录按文件修改时间排序取最新的一个文件作为候选同时支持命令行参数--log-dir覆盖。文件轮转的场景也被接住了——V2 会在会话归档时生成新文件旧文件被重命名因此我在读取循环里定期检查当前文件的大小和 inode发现变化就重新打开。Python 里判断 inode 用os.stat(path).st_ino跨平台也能用。# file_watcher.py import glob import os def pick_latest_log(log_dir: str) - str: files glob.glob(os.path.join(log_dir, *.log)) glob.glob(os.path.join(log_dir, *.ndjson)) if not files: raise RuntimeError(fno log files in {log_dir}) latest max(files, keyos.path.getmtime) return latest这个逻辑不完美但足够皮实。它不会因为某个历史会话文件被重新归档而读错因为 mtime 最大的永远是最新的活动文件。4.2 usage 字段命名与层级变化V2 最折磨人的改动是事件字段的重命名。V1 里我匹配的是type: usageV2 改成了event: llm_usage而且 model 字段从model变成了model_namesession_id 从顶层挪进了session.id。如果不做兼容解析器会静默地漏掉所有事件页面自然全零。我把新旧字段对应关系整理成了表写进代码注释含义V1 日志字段V2 日志字段事件标识type: usageevent: llm_usage输入 tokenusage.input_tokensusage.input_tokens输出 tokenusage.output_tokensusage.output_tokens缓存读取usage.cache_read_input_tokensusage.cache_read_input_tokens缓存写入usage.cache_creation_input_tokensusage.cache_creation_input_tokens模型名modelmodel_name会话 IDsession_idsession.id为了不写两套臃肿的解析代码我用了一个轻量适配层读日志第一行有效 JSON 后判断它是 V1 还是 V2 格式然后在解析函数里按版本走不同的取值路径。这个判断只做一次后面所有行都复用同一个解析策略。这样就算哪天 OpenCode 出了 V2 的补丁版本日志结构没变插件就不用动。4.3 并发会话导致指标串台V2 允许同一时间跑多个任务这在能力上是进步对我的监控脚本却是坑多个 session 会往同一个日志文件里写事件如果我的全局累加器不分 session数字会全部混在一起。比如一边开着一个长文档分析会话一边跑着代码重构页面上显示的累计消耗毫无意义因为你分不清哪部分在哪。我的解法是让采集端的全局状态从单组累加器变成按 session 分组的字典页面顶部加一个会话下拉选择器。默认选择全部聚合但大多数时候我会选择当前活跃会话。这个分组逻辑其实很简单套一层 dict 就行但确实是我适配 V2 过程中花时间最多的地方——不是技术难是容易漏。如果一个 session 的 usage 事件混进了另一个 session 的窗口速度曲线的毛刺会很明显排查起来十分痛苦。5. 90 分钟实测数据与调优记录5.1 一次真实会话的指标参考插件跑稳之后我记录了一次完整的 90 分钟代码重构会话用表格复盘指标数值备注会话时长90 分钟涉及多个文件的重构累计 Token25.8 万input 19.4 万 output 6.4 万平均 Token 速度47 tok/s60 秒滑窗瞬时峰值210 tok/s多段连续输出叠加缓存命中率整体72%前 30 分钟明显低模型切换次数3 次跨会话模式手动切换有个值得说的现象前 30 分钟的命中率只有 30% 左右后面稳定到 75% 上下。这就是上下文缓存的预热期。系统提示词加项目前缀第一次完整处理时不命中之后每次重复都命中。如果不看这个曲线我根本不会意识到预热阶段的存在只会觉得为什么这次会话的 API 账单这么高。5.2 几个值得注意的坑日志里不一定默认有 usage 事件。我一开始配置的 OpenCode 启动参数比较保守日志里只有普通对话流根本没有结构化 usage 行。后来确认需要打开对应的诊断配置V2 里有一个--show-cost类的界面开关但日志层面的用量输出由配置文件里的诊断级别决定。如果你复现时发现解析器一直拿不到数据先确认日志里到底有没有llm_usage字样别在解析代码上空耗。文件尾部容易读到半个 JSON。日志是边写边落的我用循环 readline 时可能读到被截断的半行直接 json.loads 会抛异常。处理办法很简单解析失败就跳过这一行等下一轮读文件时再重新读同一行。前提是你要用流式指针记录文件偏移不能每次打开都从头读。Windows 下文件句柄问题。在 Windows 上日志文件被轮转或归档时旧的打开句柄可能指向一个已被占用的文件后续读不到新内容。我的做法是定时检查文件大小和 inodeWindows 上可以比较 file_id发现异常就关闭重开。跨平台的第一版脚本在 macOS 上没问题拿到 Windows 上就要补这段逻辑。时间窗口的取舍。窗口太短速度曲线在峰值和低谷之间剧烈抖动窗口太长实时性名存实亡。我把窗口默认设成 60 秒每 5 秒推送一次这是一个大家都能接受的折中值。如果你的使用场景是看此刻模型是不是卡住了那 60 秒窗口会掩盖单次长等待建议再加一个最近 30 秒无输出的呼吸灯提示比单纯看曲线直观得多。5.3 监控反过来改变了我的使用习惯装上这个插件最大的收获不只是一个数字面板而是它反过来改变了我的使用方式。以前我是一个会话从头跑到尾卡住就 CtrlC 重来往往会话刚开始崩溃一次缓存白建成本白花。现在我看到命中率曲线会刻意避免在预热期反复打断也会在命中率已经很高的时候尽量保持对话连续性而不是为了清爽就随手New Session把辛苦养起来的缓存全部清零。面板还让模型成本对比变得顺手。OpenCode 可以按场景切换模型我根据日志里的 model 字段按天分组统计能清楚看到每个模型在 input、cache_read、output 上的分布。这几天我正在做一个按模型分段计价的小扩展争取把每一轮会话的估算成本也展示到页面上。有了这次适配 V2 的解析层后面再加这类功能基本就是往上叠数据源不需要再动核心链路。