Show HN: Ctrlb-decompose：在发送至LLM前从日志中去除噪音

Hacker News Top 工具
log-compression log-parsing llm-prompting devops rust cli open-source

摘要

Ctrlb-decompose 是一个开源的命令行工具和Rust库，能够将数百万条嘈杂的日志行压缩为少量结构模式，并附带统计、异常和严重性评分，使其适合LLM处理。

暂无内容
查看原文
查看缓存全文

缓存时间: 2026/07/28 15:27

ctrlb-hq/ctrlb-decompose 来源：https://github.com/ctrlb-hq/ctrlb-decompose

ctrlb-decompose

将原始日志行压缩为具有统计信息、异常和关联性的结构化模式。

将数百万条嘈杂的日志行转化为少数可操作的模式——包含类型化变量、分位数统计、异常标记和严重性评分。可作为 CLI 运行，通过 WASM 在浏览器中运行，或作为 Rust 库使用。

$ cat server.log | ctrlb-decompose
┌────────────────────────────────────────────────────────────────────┐
│ ctrlb-decompose: 1,247,831 行 -> 43 个模式 (减少 99.9%)             │
└────────────────────────────────────────────────────────────────────┘
#1 [ERROR] ██████████████████████ 18,402 (1.5%)
    ERROR [<*>] Connection to <*> timed out after <*> from ip <*>
    ip           IPv4         unique=12   top: 10.0.1.15 (34%), 10.0.1.22 (28%)
    duration     Duration     p50=120ms   p99=4.8s
#2 [INFO]  ████████████████████ 904,221 (72.5%)
    INFO  [<*>] Request from <*> completed in <*> status=<*>
    ip           IPv4         unique=1,847 top: 10.0.1.15 (12%), 10.0.1.22 (8%)
    duration     Duration     p50=23ms     p99=312ms
    status       Enum         unique=3     values: 200 (91%), 404 (6%), 500 (3%)

网站即将上线。

工作原理

ctrlb-decompose 使用两阶段标准化与聚类管道，在单次流式处理中处理日志，内存占用极低。

┌──────────────────────────────────────────────┐
│ ctrlb-decompose 管道                          │
└──────────────────────────────────────────────┘
原始日志行
       │
       ▼
┌──────────────┐
│ 时间戳        │  提取并解析时间戳（ISO 8601、Apache、
│ 提取          │  syslog、Unix 纪元等）为规范化标记，
│               │  并附带 DateTime 值。
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ CLP          │  将整数、浮点数、IP 和字符串替换为紧凑的占位符字节。
│ 编码          │  结构相同的行将生成相同的“logtype”。
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Drain3       │  基于树的相似度聚类（Drain3）将 logtype
│ 聚类          │  分组为模式。不同的标记变为 <*> 通配符。
│               │  增量处理——无需第二次传递。
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ 变量提取      │  将 CLP 解码的值与 Drain3 通配符位置
│ 与类型分类     │  合并。将每个变量分类为语义类型：
│               │  IPv4、UUID、Duration、Enum、Integer 等。
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ 统计累积      │  DDSketch 分位数（p50/p99）、HyperLogLog
│               │  基数估计、top-k 值、时间分桶，
│               │  以及水库采样的示例行。
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ 异常检测      │  频率尖峰、错误级联、低基数标记、
│               │  双峰分布及聚类数值检测。
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ 评分与        │  基于关键字的严重性（ERROR > WARN > INFO > DEBUG）、
│ 关联分析      │  时间共现、共享变量相关性，
│               │  以及跨模式的错误级联检测。
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ 输出          │  人类可读（ANSI 终端）/ LLM（紧凑 markdown）/ JSON
└──────────────┘

阶段 1 —— CLP 编码

CLP（Compressed Log Processor，压缩日志处理器）（https://www.usenix.org/system/files/osdi21-rodrigues.pdf）编码将变量令牌规范化为类型化占位符，因此结构相同的行无论实际值如何都会生成相同的 logtype：

输入: "Request from 10.0.1.15 completed in 45ms status=200"
Logtype: "Request from <*> completed in <*>ms status=<*>"

阶段 2 —— Drain3 聚类

Drain 算法在 logtype 上构建前缀树，并根据令牌相似度（可配置阈值，默认 0.4）进行分组。令牌出现分歧的地方，模板会添加 <*> 通配符。该过程增量运行——每一行只处理一次，无需第二次传递。

变量分类

提取的变量被分类为语义类型，以便进行更丰富的分析：

类型示例检测方式
IPv4 / IPv610.0.1.15CIDR 模式匹配
UUID550e8400-e29b-...8-4-4-4-12 十六进制格式
Duration45ms，3.2s数字 + 时间单位后缀
HexID0x1a2b3c4 位以上十六进制数字
Integer200解析为 i64
Float3.14包含 .，解析为 f64
EnumERROR低基数（<=20 个不同值，top-3 >= 80%）
Timestamp2024-01-15T14:22:01ZRFC 3339 模式
String其他任何内容回退类型

内存效率

  • Drain3 聚类：O(k) 复杂度，带有 LRU 淘汰策略（默认最大 10k 个）
  • 分位数：DDSketch —— 每个数值槽固定约 200 字节，不存储原始值
  • 基数：HyperLogLog++ —— 每个高基数变量约 200 字节
  • 示例：水库采样 —— 每个模式有界缓冲

安装

macOS（Homebrew）

brew tap ctrlb-hq/tap
brew install ctrlb-decompose

Debian / Ubuntu

curl -LO https://github.com/ctrlb-hq/ctrlb-decompose/releases/download/v0.1.0/ctrlb-decompose_0.1.0-1_amd64.deb
sudo dpkg -i ctrlb-decompose_0.1.0-1_amd64.deb

从源码构建

git clone https://github.com/ctrlb-hq/ctrlb-decompose.git
cd ctrlb-decompose
cargo build --release
# 二进制文件位于 target/release/ctrlb-decompose

用法

# 从 stdin 管道读取
cat /var/log/syslog | ctrlb-decompose

# 从文件读取
ctrlb-decompose server.log

# 针对 LLM 优化的输出（紧凑，节约令牌）
ctrlb-decompose --llm app.log

# JSON 输出
ctrlb-decompose --json app.log

# 显示前 10 个模式，每个附带 3 条示例行
ctrlb-decompose --top 10 --context 3 app.log

选项

ctrlb-decompose [OPTIONS] [FILE]

参数：
  [FILE]  日志文件路径（若省略或为 "-"，则从 stdin 读取）

选项：
  --human       人类可读输出（带颜色，默认）
  --llm         针对 LLM 优化的紧凑 markdown
  --json        结构化 JSON 输出
  --top <N>     显示前 N 个模式（默认：20）
  --context <N> 每个模式的示例行数（默认：0）
  --no-color    禁用 ANSI 颜色
  --no-banner   隐藏页眉/页脚
  -q, --quiet   隐藏进度消息
  -h, --help    显示帮助
  -V, --version 显示版本

输出格式

格式标志最佳用途
人类--human（默认）终端调查 —— 带颜色的可视化柱状图
LLM--llm输入到 LLM —— 紧凑、令牌高效的 markdown
JSON--json程序化消费 —— 结构化的机器可读格式

Claude Code 插件

直接从 Claude Code（https://claude.ai/code）使用 ctrlb-decompose —— 无需 CLI 知识。该插件会自动安装 ctrlb-decompose，让你通过提问即可分析日志。

安装

/plugin marketplace add ctrlb-hq/ctrlb-decompose
/plugin install ctrlb-decompose@ctrlb-hq

用法

只需用自然语言描述你的需求：

  • “分析 /var/log/app.log 中的错误”
  • “这个日志文件中最常见的模式是什么？”
  • “总结这些日志并突出异常”

Claude 会检查 ctrlb-decompose 是否已安装（如果未安装会引导你完成安装），运行分析，并解释结果——首先显示错误，指出异常，并建议下一步调查方向。

详见 plugin/README.md。

许可证

MIT

相似文章