日志故障诊断(rustfs diagnose)

对客户/现场提供的日志文件做离线故障归因:解析 RustFS 的 JSON 日志 (含 kubectl logs / docker compose / journald 采集前缀与 stderr panic 块), 匹配内置故障规则库,输出按严重度排序的诊断报告。设计与规则清单见 rustfs/backlog#1281(总纲)。

不启动存储、不联网、跑完即退,任何装有 rustfs 二进制的机器都可用。

用法

# 分析一个目录(自动处理 .zst/.gz 轮转归档)
rustfs diagnose /var/log/rustfs/

# 客户打包的多节点日志(zip/tar.gz 自动递归展开,第一层目录名作为节点标签)
rustfs diagnose customer-logs.zip

# 从 stdin 读(容器场景)
kubectl logs rustfs-0 | rustfs diagnose -

# 只看最近 24 小时,输出 Markdown 直接贴工单
rustfs diagnose logs.tar.gz --since 24h --format md > report.md

常用参数:--format text|json|md(默认 text;JSON 带稳定 schema_version)、 --since/--until(RFC-3339 或相对时间 30m/24h/7d)、--min-level、 --top N(未识别模式条数)、--samples N(每个 finding 的样本行数)。

报告解读

• 发现(按严重度):P0 数据风险 → P1 服务不可用 → P2 降级 → P3 客户端侧 → P4 提示。每条带诊断结论、建议动作、证据字段与样本行。
• 因果折叠:当症状类发现(如 quorum 刷屏)在时间上跟随其已知根因 (如盘 faulty)出现时,报告把症状折叠进根因块的"级联症状"行,根因块 提升到两者中更高的严重度位置——报告首块直接回答"最可能的原因"。 JSON 输出保留全部 findings(collapsed_into / caused 字段标注关系)。
• 时间线异常(提示):三个确定性启发,均为提示不定罪——混合 UTC 偏移 (伴签名错误时点名时钟偏移)、节点时间范围完全不重叠、时间线断档 (断档后紧跟 startup 类发现时升级为"重启证据")。
• 低频提示:命中数低于规则阈值的匹配(如零星的签名错误),仅供参考。
• 未识别的高频错误:规则库未覆盖的 WARN/ERROR 消息模板聚类。这一节是 规则库迭代的输入——反复出现的新模板请提给维护者补规则 (crates/log-analyzer/src/rules/seed/)。
• 跳过的输入与时区提示:所有被跳过的文件(二进制/超限)逐条披露; 混合 UTC 偏移会显式提醒(时钟偏移本身就是 SignatureDoesNotMatch 的常见根因)。

--redact(报告需要转发时)

把 bucket/object/AK、IPv4/IPv6、peer 与磁盘路径、节点标签、来源文件路径等客户标识替换为稳定哈希(同值同哈希,保持可关联);规则 id、诊断文本、模块 target 与 panic 源码位置(RustFS 自身代码,非客户数据)保留。样本会连同其完整 fields 一起脱敏。

覆盖是尽力而为,不是绝对保证:结构化字段与 key=value/IP 形态的文本都会被处理,但散落在自由文本里、既非字段形态也非 IP 的标识(例如句子里顺带提到的一个 bucket 名)可能仍有残留。转发前建议再抽查一遍。

自定义规则(--rules <file.json>)

支持团队可以在不等发版的情况下补规则,或热修一条误报的内置规则:

rustfs diagnose customer.zip --rules extra-rules.json

文件格式(Rule 的 JSON 表示与内置规则完全一致):

{
  "schema_version": 1,
  "rules": [
    {
      "id": "custom-oom-killer",
      "severity": "p1_unavailable",
      "category": "process",
      "title": "内核 OOM killer 终止了进程",
      "matcher": { "message_contains": "Out of memory: Killed process" },
      "diagnosis": "内核因内存不足杀掉了 rustfs 进程。",
      "suggestion": "检查内存限制与其他驻留进程;考虑调大内存或加节点。"
    }
  ]
}

• severity:p0_data_risk | p1_unavailable | p2_degraded | p3_client_side | p4_info;
• matcher:message_prefix / message_contains / message_regex / field_equals {name, value} / target_prefix / is_panic / min_level / all [..] / any [..],与内置规则同一套类型;
• 可选字段:evidence_fields、min_count(默认 1)、implies_root_cause (参与因果折叠)、anchors;
• 同 id 覆盖内置规则(用于热修误报);合并后的规则集整体校验,任何错误 (坏 regex、重复 id、空 matcher 组)会逐条打印并以退出码 2 失败——不会 带着半坏的规则集分析;
• 外部规则的 anchors 不受 CI 锚点守卫约束,质量由文件作者自担。

已知边界

• panic 只出现在 stderr:若客户只采集了 stdout,panic 不会出现在日志里, 但 rwlock ... poisoned 类发现会提示"曾发生 panic"。
• 审计日志(camelCase 外发流)不在本工具范围内。
• 规则锚点由 CI 守卫(rustfs/backlog#1289)保证与源码日志文案同步。