clean-log-toolkit

v0.2.0

一款轻量、可靠、纯本地的日志处理工具集，专为工作代理（work agents）日常高频任务而设计：读取他人发送的日志文件、自动识别其格式、定位真实问题，并生成可直接粘贴至工单（ticket）的摘要。完全基于 Python 3 标准库实现，不依赖任何外部工具或服务：无 awk/sed/jq 封装调用，无需 pip 安装第三方包，亦无任何远程 API 调用。

本能力是 “clean-*” 工具三部曲中的第三项：

• clean-csv-toolkit —— 处理结构化表格数据
• clean-text-toolkit —— 处理非结构化文本
• clean-log-toolkit —— 处理带时间戳的半结构化日志

本能力的功能

• scripts/parse.py —— 将日志文件解析为结构化行数据。通过嗅探前约 50 行内容，自动识别 apache-common、apache-combined、nginx-access、syslog 和 json-line 五种常见格式；若均不匹配，则回退至通用提取器（提取时间戳 + 日志等级 + 消息体）。可通过 --regex PATTERN 参数传入含命名捕获组（named groups）的正则表达式，自定义解析逻辑。输出支持 .csv、.tsv 或 .jsonl 格式。
• scripts/errors.py —— 聚合日志中的错误事件。默认按等级（WARN / ERROR / FATAL）统计；按分钟 / 小时 / 天对时间线进行分桶；将每条消息归一化为“指纹”（fingerprint）——即替换其中的数字、UUID、十六进制令牌、文件:行号对及内嵌时间戳为占位符；最终呈现出现频次最高的前 N 组错误。支持输出 JSON / Markdown / CSV 报告，或直接打印单屏摘要。
• scripts/grep.py —— 日志感知型 grep 工具。支持组合使用 --pattern REGEX、--not-pattern REGEX、--level LVL[,LVL2...]、--since TIMESTAMP、--until TIMESTAMP，以及上下文行参数 -B / -A / -C，在单次扫描中完成全部过滤逻辑。
• scripts/follow.py（v0.2.0 新增）—— 等效于 tail -F 的日志感知式实时流式监听工具。随新行写入实时输出，支持与 grep.py 完全一致的 --pattern / --not-pattern / --level / --since 过滤能力；自动检测日志轮转（通过 inode 变更或文件截断触发透明重开）；--max-events N 可在匹配 N 条事件后优雅退出（CI 友好）；--timeout SECONDS 可在无新日志到达时超时退出；--json 模式为每行匹配输出一个带提取出的时间戳与等级字段的 JSON 包络（envelope）。
• scripts/check_deps.sh —— 验证系统中是否存在可用的 python3 命令。

本能力不提供的功能

• 实时 tail-and-follow 功能现已由 scripts/follow.py 提供（v0.2.0 新增）。
• 不调用任何大语言模型（LLM）、Web 服务或远程 API。
• 不会向调用者指定的输入/输出路径之外的任何位置写入数据。

快速上手

1. 解析未知格式的日志文件

# 自动识别日志格式
python3 scripts/parse.py app.log app.csv

# 或显式指定格式
python3 scripts/parse.py access.log out.jsonl --format apache-combined
python3 scripts/parse.py syslog.txt out.csv --format syslog
python3 scripts/parse.py events.log out.csv --format json-line --fields ts,level,msg

2. 使用命名组正则表达式定义自定义格式

python3 scripts/parse.py app.log structured.csv 
    --regex '^(?P\S+)s+(?P\S+)s+(?P.*)$'

3. 聚合错误并生成报告

# 单屏摘要
python3 scripts/errors.py app.log

# 按分钟分桶，输出前 20 组高频错误
python3 scripts/errors.py app.log --bucket minute --top 20

# 仅统计特定等级（如 ERROR 和 FATAL）
python3 scripts/errors.py app.log --level ERROR,FATAL

# 生成 Markdown 报告，可直接粘贴至工单
python3 scripts/errors.py app.log --output report.md

# 或生成 JSON 报告供下游工具消费
python3 scripts/errors.py app.log --output report.json --bucket hour

# 或仅导出时间线 CSV（按分钟分桶）
python3 scripts/errors.py app.log --output timeline.csv --bucket minute

errors.py 会对消息进行指纹（fingerprint）归一化处理，使仅在数字 / UUID / 文件行号等局部差异上不同的重复错误合并为同一组，并统计总次数。例如：Connection timeout to 10.0.0.5 after 1234ms 与 Connection timeout to 10.0.0.7 after 567ms 各出现 25 次，将被归并为一组 Connection timeout to ... after ms，总计 50 次。

4. 日志感知型 grep

# 匹配模式 + 等级过滤
python3 scripts/grep.py app.log --pattern "Database" --level ERROR,FATAL

# 时间窗口过滤
python3 scripts/grep.py app.log 
    --since "2026-05-10T10:00:00Z" 
    --until "2026-05-10T11:00:00Z"

# 上下文行（每处匹配前后各 1 行）
python3 scripts/grep.py app.log --pattern "FATAL" -C 1 --with-line

# 排除干扰性日志行，保留其余内容
python3 scripts/grep.py app.log --level ERROR --not-pattern "heartbeat"

# 反向匹配：仅保留不满足条件的行
python3 scripts/grep.py app.log --pattern "INFO" --invert

--since 与 --until 支持与 parse.py 相同的时间戳格式：ISO 8601（如 2026-05-10T10:00:00Z、2026-05-10 10:00:00，支持微秒和时区）；Apache 风格（10/May/2026:10:00:00 +0000）；Syslog 风格（May 10 10:00:00，年份默认为当前年）。

退出码（Exit codes）

该 0 / 1 / 2 编码规范在全部三个脚本中保持一致，便于无缝接入 shell 管道：

# 先解析为 JSONL，再汇总错误，最后提交至工单
python3 scripts/parse.py raw.log structured.jsonl 
  && python3 scripts/errors.py raw.log --output ticket.md 
  && cat ticket.md

安全性保障

• 纯 Python 3 标准库实现，无任何第三方依赖。
• 不使用 subprocess 模块，不执行任何 shell 命令。
• 所有文件路径均经严格白名单正则校验，拒绝包含 shell 元字符的路径；复用 clean-csv-toolkit 与 clean-text-toolkit 中相同的 safe_path() 工具函数。
• 脚本仅读取调用者传入的输入路径，且仅向调用者指定的输出路径写入数据。
• 所有输入默认以 UTF-8 编码读取；若失败，则依次尝试 utf-8-sig、cp1252、latin-1；所有输出统一采用 UTF-8 编码。

时间戳与日志等级识别机制

_common.py 内置一个实用型时间戳解析器，按如下优先级顺序尝试匹配，命中即止：

2026-05-10T10:00:00.123456+00:00     (含时区与微秒的 ISO 8601)
2026-05-10T10:00:00+00:00            (含时区的 ISO 8601)
2026-05-10T10:00:00.123Z              (UTC 时区 Zulu 格式，含毫秒)
2026-05-10T10:00:00Z                  (UTC 时区 Zulu 格式)
2026-05-10T10:00:00                   (无时区的 ISO 8601)
2026-05-10 10:00:00                   (空格分隔)
2026/05/10 10:00:00
10/May/2026:10:00:00 +0000           (Apache 通用日志格式)
May 10 10:00:00                       (Syslog 格式，无年份)

日志等级不区分大小写地从以下标记中识别，并映射为标准名称：TRACE、DEBUG、INFO、NOTICE、WARN（来自 WARN/WARNING）、ERROR（来自 ERROR/ERR）、FATAL（来自 FATAL/CRITICAL/CRIT/EMERG/EMERGENCY）。

已知限制

• 基于正则的解析器注重实用性而非严格性——只要 Apache / nginx / syslog 日志行结构大致符合，允许存在轻微格式瑕疵。
• errors.py 的指纹归一化属于启发式最佳实践（best-effort heuristic）。语义上不同但恰好仅在数字 / 哈希值上存在差异的两条错误消息，可能被错误合并；若此行为影响分析，请增大 --top 参数值并人工检查样本。
• parse.py 不支持实时跟踪日志文件。如需 tail-follow 功能，可自行使用 tail -F file | ... 管道；若社区反馈强烈，内置跟随器将在 v0.2 版本中提供（注：该功能已在 v0.2.0 实现）。

协同使用场景

• clean-csv-toolkit —— 将 parse.py 的输出（CSV / JSONL）作为输入，交由 inspect、validate、pivot 或 transform 等命令进一步加工，将原始日志转化为可汇报的结构化报表。
• clean-text-toolkit —— 将 parse.py 的输出与 text-toolkit/redact.py 配合使用，在共享日志转储前脱敏（scrub）个人身份信息（PII）。

v0.2.0 更新内容

• 新增 scripts/follow.py：支持日志感知的实时 tail-and-follow 功能。具备与 grep.py 完全一致的 --pattern / --not-pattern / --level / --since 过滤能力；自动检测日志轮转（inode 变更或文件截断均触发透明重开）；--max-events N 和 --timeout SECONDS 使其适用于 CI 场景；--json 模式为每条匹配行输出一个含提取时间戳与等级字段的 JSON 包络。此举已解决 v0.1.x 文档中唯一明确列出的限制项。

v0.1.1 更新内容

• 修复时间戳解析器：grep.py 的 --since 和 --until 参数现在支持纯日期格式，如 2026-05-09、2026/05/09 和 09/05/2026（欧洲格式）。此前仅接受完整 ISO 8601 时间戳，导致用户试图按日历日期过滤时收到 could not parse --since 错误。

v0.1.0 更新内容

• clean-log-toolkit 首次公开发布。
• 包含三个核心脚本：parse.py、errors.py、grep.py。
• 共享 _common.py 模块，提供 safe_path、iter_lines、parse_timestamp、extract_timestamp、extract_level 等基础工具函数（设计与 clean-csv-toolkit/scripts/_common.py 和 clean-text-toolkit/scripts/_common.py 保持一致）。
• 通过嗅探前 50 行自动识别 5 种日志格式。
• 零第三方依赖；可在任意预装 Python 3 的系统上运行。

许可证

MIT