模型读日志之前,先过一道规则

ops-agent 建造笔记第 15 篇:确定性日志粗筛 logscan 怎样在模型读语义之前做级别与关键词收口、模式聚类和时间桶分布,为什么部分扫描必须如实标注、无命中不等于没问题,以及 rc.4 把 stderr 与非零退出收进采集失败语义。

模型读日志之前,先过一道规则

《ops-agent 建造笔记》第 15 篇(续篇分篇) 代码基线:v0.1.0-rc.4,提交 8dfa085(2026-11-09 候选版);前 13 篇仍固定 v0.1.0-rc.1 对照实现:agent/logscan.py、agent/tools.py 的 logscan 工具定义与 SCHEDULED_TOOLS 续篇入口:文章锁在 rc.1,代码已经走到 rc.4


0. 第 2 篇的规矩,延伸到日志

第 2 篇讲巡检不交给模型判:固定探针、五种状态、采不到就留缺口,模型可以解释采样结果,但不能替规则下「正常」的结论。那条链路覆盖的是连通性、资源和服务。日志一直是个例外——排查时模型要自己翻 grep / tail 的输出,逐行读语义。

v0.1.0-rc.2 把这条思路补到了日志上,新增只读工具 logscan。agent/logscan.py 开头那句定位写得很直白:「模型读语义之前的规则第一道」。海量日志先按规则收口,模型只看聚类报告和少量样本,不逐行扫原始日志;输出即证据,每条结论附来源命令。

这不是为了让模型少干活。逐行把原始日志塞进上下文,成本高、脱敏难、还不可复核:一句「看起来没什么问题」没有留下可回看的依据。把第一道交给确定性规则,至少能说清「按什么规则收口、扫了多少行、哪些没扫到」。


1. 规则第一道具体做什么

三步,都在 agent/logscan.py 里,不依赖 API Key:

  1. 收口。按错误级别(error 优先 warn,一行多命中取高级别)和关键词筛行。关键词覆盖 exception、traceback、failed、timeout、refused、denied、out of memory、reset by peer、非 0 退出码,以及 nginx access 里的 5xx 状态码。
  2. 聚类去重。把行首时间戳、IPv4、UUID、十六进制和数字归一化成 <ip> / <id> / <hex> / <n> 一类占位符,同一故障的重复报错聚成一团,而不是一万条独立异常。
  3. 时间分布。能解析出行首时间戳(ISO/journalctl/docker、nginx、syslog 三种格式)就按 10 分钟分桶,解析不了退化为行号区间,让「什么时候开始变多」有据可查。

最后交给模型的,是 top N 个可疑聚类的少量样本(每行截断 200 字符)和行号/时间指针;想深挖某一团,再按指针去针对性复核。来源三选一:本机日志文件路径、journalctl 单元名、docker 容器名;since / until 限定时间窗,pattern 可再聚焦一层正则。远程目标只允许后两者——本机没法替远端核实一个文件路径。

工具 schema 里那句描述把边界写死了:「日志量大时先跑它,不要直接用 grep/tail 逐轮硬翻原始日志」。


2. 参数也是证据的一部分

一组默认值决定了这份报告能覆盖多少,所以它们必须露出来:

参数 默认 / 上限 为什么重要
lines 200,000(1–2,000,000) 默认只扫最近 N 行;故障定位通常有时间窗
top 10(1–50) 报告里给模型看的聚类数
扫描时间预算 30 秒 超时按部分扫描如实标注
聚类组上限 5000 全唯一行输入也不能无界占内存,超限如实标注截断
样本长度 200 字符/行 只给指针和片段,不给整本日志

「部分扫描」「截断」这些标注不是装饰。工具 schema 里还直接写着「无命中 ≠ 没问题」——粗筛规则之外的语义异常仍需针对性复核。这句和第 2 篇里「未配置 services 只能算不完整,不算正常」是同一条规矩:没采到、没扫完、规则没覆盖,都不能被一句「没有异常」盖过去。

路径命中敏感文件/目录规则时,和 read / bash 一样直接拒绝,连审计里也只留 logscan-deny;样本统一经脱敏出口。它被放进 tools.SCHEDULED_TOOLS,和 inspect 一起属于确定性检查,所以子代理和无人值守的定时上下文都能用——第 8 篇讲只读子代理的边界,第 6 篇讲无人值守只有只读工具集,这里没有为它们开新的写通道。


3. rc.4 补的是「采集失败」

规则再细,也得先保证喂给它的日志是真采到的。rc.4 的 R09 与发布前机器评审补了两处:

  • 本机:日志采集原先只保留 stdout,docker logs 等写到 stderr 的错误日志会被静默丢掉;现在合并两路输出,非零退出统一按采集失败报错。
  • 远程:复审发现共享远程采集函数还把「非零退出且带有错误输出」当成日志内容,一并改为拒绝;诊断摘要先脱敏,本机与远程入口保持一致。

对应的定向回归 5/5 通过,远程 Docker / journal 的非零输出回归先红后绿,正常输出保留。命令错误、输出不完整、采集中途失败,都不能被聚类成「日志里没有问题」——否则第一道规则越精细,越会给一个错误的结论提供可信的外表。

这一篇讲的是能力边界,不是验收结论。logscan 的回归与本机演练不能替代真实主机上的验收;本组续篇按 rc.4 口径,真实 SSH 恢复、断线 unknown 防重放、服务后验与修复版本七天观察仍未完成,证据表在第 17 篇。

对照源码与证据


系列总览 · 目录 · 续篇入口 · 上一篇:第五个壳,没有终端确认框 · 下一篇:批准一张变更单,不再是批准一条命令