log-ai-compressor
日志根因带行号和 sha256,改一个字节就露馅。 给查日志的运维 / 后端 / 安全:本机跑,日志不出网,0 次 API 调用。
每条结论 = 原文行号区间 + 那段原文的 sha256;verify 重读原文逐条核对,
日志被改过直接判 TAMPERED(退出码 1)——你不必相信工具,自己核。
先看一份 24 行日志的真实输出:根因、4 条引用、每条的原文行号和 sha256,全部在本机算完。
90 秒跑样例 · 三分钟自证 · 复现全部数字 · English · 我要一条真实复现
改一个字节会怎样:
$ 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。
三分钟自证:装 → 跑 → 复核
$ pip install log-ai-compressor
$ 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。
它长什么样:一份 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真跑一遍盯着。
打开界面(推荐入口)
| 你的环境 | 一条命令 |
|---|---|
| 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.1 # PyPI 上就是 3.0.1(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.1,能不能装以 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.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| log_ai_compressor-3.0.1.tar.gz | 1.8 MB | Without provenance | Details for log_ai_compressor-3.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| log_ai_compressor-3.0.1-py3-none-any.whl | Python 3 | none | any | Details for log_ai_compressor-3.0.1-py3-none-any.whl |
Total release size: 2.2 MB
Release files / log_ai_compressor-3.0.1.tar.gz
| Download URL | log_ai_compressor-3.0.1.tar.gz |
|---|---|
| Size | 1.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f0be1183794e1cccced05fc4c21da7ed90997c4384668ebce732e2258ec8d08f
|
|
BLAKE2b-256 checksum How to use checksums |
abfcb6102ae9d1c5730a05906b63abeaeae686347023466cb94c780c888c71c8
|
| 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.1-py3-none-any.whl
| Download URL | log_ai_compressor-3.0.1-py3-none-any.whl |
|---|---|
| Size | 315.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9a369858cba20606b30bf4ebce3c39d7d88b07827364cfa2d9681c06bef9a2d3
|
|
BLAKE2b-256 checksum How to use checksums |
8263e40365017a5453592b1033daed79ad8c9f5e9c32d8f41a61fee09093d700
|
| 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.1
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.