Skip to main content

log-ai-compressor

日志根因带行号和 sha256,改一个字节就露馅。 给查日志的运维 / 后端 / 安全:本机跑,日志不出网,0 次 API 调用。

每条结论 = 原文行号区间 + 那段原文的 sha256;verify 重读原文逐条核对, 日志被改过直接判 TAMPERED(退出码 1)——你不必相信工具,自己核。

先看一份 24 行日志的真实输出:根因、4 条引用、每条的原文行号和 sha256,全部在本机算完。

Release Tests

90 秒跑样例 · 三分钟自证 · 复现全部数字 · English · 我要一条真实复现

本机日志取证层首页:拖入日志或浏览文件,级别默认只留 ERROR/WARN,点开始分析

改一个字节会怎样:

$ log-ai-compressor verify --report examples/app_report.json
证据:共 4 条引用,匹配 3 条,失配 1 条,源不可读 0 条,缺行号 0 条,缺摘要 0 条

自校验结论:TAMPERED        # 退出码 1

  ✗ MISMATCH c3801f905159 examples\app.log 期望 bc5b93cec7cde01c 实际 1b8242c1671f1e29

这 6 行不是手写的:先跑下方三分钟自证生成 examples/app_report.json,再把 examples/app.log 里的 db-primary 改成 db-primarY,重跑 verify 即得上图;改回即 VERIFIED。

判定没有「大部分通过」这一档,四档见 docs/CLI.md。

三分钟自证:装 → 跑 → 复核

$ python -m pip install -i https://pypi.org/simple "log-ai-compressor==3.0.3"
$ python -c "import log_ai_compressor, pathlib, shutil, os; os.makedirs('examples', exist_ok=True); shutil.copy(pathlib.Path(log_ai_compressor.__file__).parent/'data/examples/app.log', 'examples/app.log')"
$ log-ai-compressor run examples/app.log -f json -o examples/app_report.json
$ log-ai-compressor verify --report examples/app_report.json
模式:复核已导出报告
对象:报告 app_report.json
证据:共 4 条引用,匹配 4 条,失配 0 条,源不可读 0 条,缺行号 0 条,缺摘要 0 条

自校验结论:VERIFIED
每条结论都能在原始日志里逐行复核。

同一条命令加 --json,机器可读字段是 checked: 4 / matched: 4 / mismatched: 0。

只 pip 安装、没有 clone 仓库也能跑:上面第二条 python -c 会把 wheel 里的 data/examples/app.log 取到当前目录的 examples/app.log,后两条命令直接可用。

它长什么样:一份 24 行日志的真实输出

examples/app.log(24 行、8 条错误、4 种类型)跑出来是这样 —— 下面这段就是它的真实输出, 你可以自己跑一遍对上:

$ log-ai-compressor run examples/app.log
⚠ 报告全文 ≈2.4k tokens,比原始日志(≈379 tokens)还大 —— 建议只用摘要:log-ai-compressor run examples/app.log -f summary
【日志分析摘要】examples/app.log
原始日志 ≈379 tokens → 摘要 ≈234 tokens(压缩 38%)
确定性指纹 `48e5781aafc4b27fe0f68c5847afe6d891936ac9f2e0af59aefaa9860f9c2886`(同一份日志跑两遍必须完全一致)
总行数 24,错误 8 行,去重后 4 种,时间范围 2024-03-15 08:00:00 ~ 2024-03-15 08:00:25。
已定位根因:java.net.ConnectException: Connection refused(另有 1 个根因候选)

(证据出处末尾 16 位十六进制 = 该段原文 sha256 前 16 位,可自行复核)
1. [P0 | ERROR | ×3 | 根因 | 行 4~13] authorization failed: connection refused to db-primary:5432
   证据出处:L4 bc5b93cec7cde01c
   -> 因果链源头(1 个错误由其衍生)
2. [P0 | ERROR | ×3 | 行 6~11] request 8812 failed: upstream unavailable
   证据出处:L6 21d12907c3115d34
3. [P0 | ERROR | ×1 | 根因 | 行 18~22] java.net.ConnectException: Connection refused
   证据出处:L18-L22 68af24f230baff5c
   -> Caused-by 因果链直连,根因:java.net.ConnectException: Connection refused
4. [P0 | ERROR | ×1 | 行 23~23] stock check timeout after 3000ms item=SKU-7781
   证据出处:L23 a72b9f38845a14ed
报告已导出: examples/app_report.md(MD,9.4 KB)

拿到结论之后,三个动作

$ log-ai-compressor run examples/app.log -f json -o examples/app_report.json   # 先导出 JSON 报告
$ log-ai-compressor verify --report examples/app_report.json   # ① 自校验:重读原文,逐条核对 sha256
$ log-ai-compressor evidence examples/app_report.json           # ② 看原文:这条结论引用的那几行
$ log-ai-compressor run examples/app.log -f summary             # ③ 投喂:只把精简摘要交给模型

① 只给判定(VERIFIED / TAMPERED / UNVERIFIABLE / NO_EVIDENCE),不指控你;② 与 ① 共用同一套回读;③ 默认输出到 stdout。第 3 条标题指向链尾真因(L18–L22),不是外层症状。

首屏这几条命令由 tests/test_readme_sample_is_reproducible.py 真跑一遍盯着。

打开界面(推荐入口)

本机日志取证层:24 行样例日志跑出的「已定位根因」+「全部核对通过 VERIFIED」

你的环境 一条命令
Windows 双击仓库根目录的 start.bat —— 自己找 Python、缺依赖就装、装完开浏览器
任意平台 pip install "log-ai-compressor[web]" && log-ai-compressor web

三步就到结论:① 拖日志进窗口(或点「浏览…」)→ ② 级别默认只留 ERROR/FAIL/WARN → ③ 点「开始分析」。第一屏给的是「已定位根因 / 证据不足」这一张卡,不是一堆模板簇; 点卡下方复核证据出处,工具重读原始日志逐条核对,给出 VERIFIED 或 TAMPERED。

界面零构建、零 CDN(唯一例外:/api/docs 的 Swagger 样式表走 jsdelivr),断网可用。

装上就用

pip install log-ai-compressor==3.0.3   # PyPI 上就是 3.0.3(2026-11-20 发布),硬依赖只有 PyYAML 一个
你要做的事 命令
分析一份日志 log-ai-compressor run app.log -o report.md
接管道(不用先落盘) kubectl logs -f deploy/api | log-ai-compressor run - -f json
只看最近几千行(行号仍指回原文件) log-ai-compressor run app.log --tail 5000
试带 Caused by 链的样例 log-ai-compressor run examples/sample_system.log -f json
试 GBK 编码 log-ai-compressor run examples/sample_gbk.log -f summary
拿机器可读的 JSON(stdout 就是 JSON) log-ai-compressor run app.log -f json
比对发版前后 log-ai-compressor compare v1.log v2.log -f json
复核一份报告的出处 log-ai-compressor verify --report report.json
要界面(拖拽 + 卡片 + 复核按钮) 见上文打开界面:start.bat 或 log-ai-compressor web
让 AI Agent 调本机日志 pip install "log-ai-compressor[mcp]" && log-ai-compressor mcp --install claude-code

首次运行(2026-10-22 本机实测,Windows / Python 3.11):装依赖 2.3 秒(有 pip 缓存),之后每份小日志 0.19~0.25 秒;大文件流式处理,Python 堆峰值约 12 MB,不随文件增大。Windows 可双击 start.bat 自动装依赖并打开浏览器。

你不必相信这个工具

每条结论带原文行号区间 + sha256;verify 重读原文逐条核对,改一个字节就 TAMPERED。 我们撤回过一个复现不了的 91.4% 召回率,记录在 FAQ Q10。一个主动撤回招牌数字的项目,剩下的数字才有分量。

它会漏什么

二进制、混合编码、超长单行、没有 trace_id 的多服务日志、--tail 配管道等场景,实测边界见 docs/LIMITS.md。

这些数字不能证明什么

不证明根因准确率高于云平台,不证明在所有日志上都赢 Drain3,不证明压缩比能外推到你的日志。完整边界见 docs/LIMITS.md。

证据:十集全量 GA 88.68% vs Drain3 71.58%

数据集 标注事件 本项目(交付 top20) 本项目(同预算 32k) 本项目(全量) Drain3 LogsLop tail @32k grep @32k
Proxifier 11 90.9% 90.9% 90.9% 72.7% 27.3% 63.6% 45.5%
Apache 29 65.5% 100.0% 100.0% 93.1% 44.8% 27.6% 34.5%
OpenSSH 38 52.6% 100.0% 100.0% 92.1% 34.2% 55.3% 26.3%
Hadoop 236 8.5% 98.3% 98.3% 80.5% 13.1% 32.6% 13.1%
Zookeeper 89 22.5% 75.3% 75.3% 76.4% 23.6% 79.8% 9.0%
Linux 338 4.7% 77.2% 77.2% 66.6% 55.6% 3.6% 3.6%
HealthApp 156 12.8% 82.1% 82.1% 83.3% 7.1% 32.1% 3.8%
Mac 626 3.2% 77.2% 92.0% 72.2% 16.1% 24.8% 5.1%
HPC 74 20.3% 73.0% 73.0% 87.8% 4.1% 1.4% 4.1%
OpenStack 48 39.6% 75.0% 75.0% 41.7% 18.8% 20.8% 8.3%

三个口径:交付口径 1 胜 9 负;同预算 32k 7 胜 3 负;全量口径 7 胜 3 负。同机同口径,不是全球榜单;CSV、分母、复现命令见 docs/BENCHMARK.md 与 docs/PROOF.md。

换一把尺子:PA / GA

PA 85.05% vs 58.06%(+27.00pp),GA 88.68% vs 71.58%(+17.10pp)。两个口径都胜(逐数据集 PA 10 胜 0 负、GA 8 胜 2 负)。

工程指标(可对账)

指标 实测值
生产代码 10,950 行(36 个模块),硬依赖只有 PyYAML
测试 2,431 用例(2026-11-20 本机 Windows 实测:2,429 passed / 2 skipped / 0 failed),覆盖率 94.15%(漏行 312 / 5,332 语句)
CI Ubuntu 3.11 / 3.12 / Windows 3.12 三矩阵,十二道门禁:ruff / 单测+覆盖率 / 对抗评分卡 / 确定性指纹 / 自证脚本 / 构建可复现性 / 变异存活率记分卡 / SAST / 依赖漏洞扫描 / 性能回归 / 产物审计 / sdist 自测
自证脚本 现已断言 11 条主张;这里再复述一次:11 条主张,含「README 工程指标与架构树必须与仓库一致」「README 写的条数不许漂」「每一处基准表逐格对账实测基线」
依赖 运行时硬依赖只有 PyYAML 一个,全部 16 条声明依赖经 pip-audit 扫描无已知漏洞
隐私 本地分析不出本机;可选 AI 解读只发送脱敏后的片段(默认关闭、需显式同意)
CI 参考 run run 40765275081,head 850550f2,结论 success(ubuntu-3.12 覆盖率出处)

其中「5,332 语句」跨平台必然相同(它由源码静态解析决定),漏行数才随平台变。

覆盖率的分母比上面那行代码量小:pyproject.toml 的 [tool.coverage.run] omit 排除了 cli.py(薄适配层,1,041 行,只做参数解析与格式分发)。所以这个覆盖率是在 9,909 行上算的,而「10,950 行生产代码」含它 —— 两个数字口径不同,别拿它们互推。

不能证明什么 实测边界
压缩比能外推到你的日志 20,509 倍是 OpenStack 全级别摘要的单集上限,不是通用承诺:15,299,983 → 746 tokens ≈ 20,509 倍(15,299,983 ÷ 746);换数据集、换 --context,数量级就变

MCP(给 Agent 用)

server.json 已提交官方 Registry;Registry 上的条目落后于本地 3.0.3,能不能装以 PyPI 为准。 安装:pip install "log-ai-compressor[mcp]" && log-ai-compressor mcp --install claude-code。 Registry 验证 PyPI 包时抓的标记:

mcp-name: io.github.hu-chenyu/log-ai-compressor

查证记录见 docs/MCP.md。

🧰 能力

  • 取证:每条结论绑定 evidence_id + 文件 + 行号区间 + 原文 sha256;verify 改一个字节即 TAMPERED。
  • 确定性:同一份日志两次分析的指纹逐字节相同(耗时/速率已排除);归档存指纹,不存报告文件。
  • 置信三档:CONFIRMED / LIKELY / INSUFFICIENT;CONFIRMED 必须能取出原文引用,取不到就降档并列出还缺什么。
  • 解析与调用链:ISO / syslog / logcat / logfmt / JSON Lines / 中式堆栈,UTF-8/GBK/UTF-16/32 + .gz/.zip;有 trace_id 时重建跨服务链路。
  • 界面与 AI:Web 界面零构建、离线可用;AI 解读可选,不配 Key 也能完整用。

完整清单与边界见 docs/FEATURES.md。

能力边界

不做持续告警、不做 tracing、不比云平台根因准确率;这三条是有意取舍,不是没做完。 完整边界与“谁行”见 docs/LIMITS.md 和 docs/THREAT_MODEL.md。

🗂 深入

文档 里面有什么
docs/BENCHMARK.md 全部实测的方法学、口径、公平性说明、两处落后的病因、撤回记录
docs/REPRODUCIBILITY.md 工程指标、CI 门禁、run 出处与逐步复现
docs/CLI.md 完整命令行用法 + 自定义解析规则
docs/FAQ.md 逐条回答质疑:「凭什么比 Drain3 强」「自信错误率是不是门槛设高了」…
docs/LIMITS.md 实测边界、它会漏什么、这些数字不能证明什么
docs/security/INDEX.md 每日安全台账:依赖漏洞 / 疑似密钥 / 危险调用,逐日可查

其余(架构 / 评测 / 定位 / 贡献 / Agent 契约)见 docs/ 与 AGENTS.md。

复现本文所有数字:

python scripts/fetch_datasets.py --all   # 下公开数据集
python scripts/benchmark_loghub.py       # 证据保留率对照
python scripts/prove.py                  # 自证:不必相信作者,自己跑

🙏 外部复现者致谢

这个仓库的每个数字目前都是作者自证。下表只登记真正跑过的人(规则见 docs/REPRODUCIBILITY.md 第八节):

# 环境 结论 日期
— 暂无 等你来做第一个 —

想进这份名单:按 Issue #IKVUSO 里的两条命令跑一次,回帖写清「操作系统 + Python 版本 + 退出码」,署名或匿名都行,成败都算数。

License

MIT

Metadata

Release files for log-ai-compressor 3.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for log-ai-compressor 3.0.3
File Size Uploaded Provenance Actions
log_ai_compressor-3.0.3.tar.gz 1.8 MB Without provenance Details for log_ai_compressor-3.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for log-ai-compressor 3.0.3
File Interpreter ABI Platform Actions
log_ai_compressor-3.0.3-py3-none-any.whl Python 3 none any Details for log_ai_compressor-3.0.3-py3-none-any.whl

Total release size: 2.2 MB

Release files / log_ai_compressor-3.0.3.tar.gz

Download URL log_ai_compressor-3.0.3.tar.gz
Size 1.8 MB
Tags Source
SHA-256 checksum
How to use checksums
7d4c74f74496973547c9461a1c62e0f80b0ff8d0a488e98050af72892140f160
BLAKE2b-256 checksum
How to use checksums
a30c126d28da158d1d012d1881ba4f89d2117595ee5c848409ada46a68efe164
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Release files / log_ai_compressor-3.0.3-py3-none-any.whl

Download URL log_ai_compressor-3.0.3-py3-none-any.whl
Size 315.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3190e8103b02761689eba61ab5ffbce8d82270c3444b812390725821f297c026
BLAKE2b-256 checksum
How to use checksums
e201b24fc0390257f0b11a8069faa5b597e5697499c041dc449faba2b591fc74
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Security for log-ai-compressor 3.0.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.0.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page