# 客户的错误日志，不先归一化就别急着计数

> 用 re 和 Counter 写几十行 Python，把杂乱的日志文件变成能带进客户会议的错误排行表。

原文: https://fdetimes.net/zh/guides/normalize-error-logs-before-counting/

根据 Python logging 文档，`Logger.exception()` 会在消息之外同时写入堆栈跟踪。所以客户发来的日志文件很少是一行一个错误那么整齐：一个错误后面可能拖着十行 traceback，而这些行既不以时间戳开头，也没有日志级别。

还有第二个问题。错误消息里通常带着订单号、毫秒数和内存地址。如果直接统计原始消息，同一个超时错误会拆成几百个各出现一次的分组，表格给出的结论就是：没有哪个错误特别突出。

对前线部署工程师（FDE）来说，客户发来日志后，第一个问题几乎总是“哪个错误最多？”。本指南只用标准库 `re` 和 `collections.Counter`，写一个小 Python 脚本来回答这个问题。你需要 Python 3 和一个可以练手的日志文件。

## 先准备一份示例日志

下面的格式是虚构的简化示例。客户真实的日志会有所不同，但结构通常相似：行首是结构化字段，行尾是自由文本。把它保存为 `app.log`：

```text
2026-11-03 09:14:22 [ERROR] [payments] Timeout calling bank API order=84213 after 3000ms
2026-11-03 09:14:25 [INFO] [api] GET /orders/84213 200
2026-11-03 09:14:31 [ERROR] [payments] Timeout calling bank API order=90117 after 3012ms
2026-11-03 09:15:02 [ERROR] [worker] Failed to process job 5521
Traceback (most recent call last):
  File "worker.py", line 42, in run
KeyError: 'customer_id'
2026-11-03 09:15:40 [ERROR] [worker] Failed to process job 5530
Traceback (most recent call last):
  File "worker.py", line 42, in run
KeyError: 'customer_id'
```

注意其中有六行不以时间戳开头。它们是 job 5521 和 5530 两次失败的 traceback，每一段都必须跟着上面那一行走。

如果客户用的是 Python 的默认配置，格式会更简单。按照 logging 文档，默认格式是 `severity:logger name:message`。标准级别从 DEBUG 到 CRITICAL，过滤用的列表已经现成。

## 第 1 步：写一个三个月后还看得懂的正则

新建文件 `logtop.py`。正则要写成原始字符串（加 `r` 前缀），这样 Python 不会在正则引擎看到之前先处理 `\d` 这类反斜杠序列。再用 `re.VERBOSE` 把模式拆成带注释的几段：

```python
import re
from collections import Counter

LINE = re.compile(r"""
    ^(?P<ts>\d{4}-\d{2}-\d{2}\ \d{2}:\d{2}:\d{2})\s+  # 时间戳
    \[(?P<level>.+?)\]\s+                             # 日志级别
    \[(?P<logger>.+?)\]\s+                            # logger 名称
    (?P<msg>.*)$                                      # 自由文本消息
""", re.VERBOSE)
```

每个 `(?P...)` 都是一个命名分组。这是 Python 特有的语法，可以按名称而不是按位置取出字段。模式在文件顶部用 `re.compile()` 编译一次。`re` 文档指出，同一个表达式要多次运行时这样更高效，这里就是要跑几百万行。

容易忽略的细节是 `.+` 后面的 `?`。它让量词变成非贪婪模式，尽可能少地匹配字符。对上面的示例行来说，去掉 `?` 正则仍能正确拆分，因为匹配器会回溯，直到模式的剩余部分能够匹配。

麻烦出在消息本身带方括号的时候。试一行时间戳之后是 `[ERROR] [api] Rejected [role] [admin] for user 7` 的日志。贪婪版本会停在仍能匹配的最远一个 `]`，得到的 `level` 是 `ERROR] [api] Rejected [role`，`logger` 是 `admin`。非贪婪版本停在第一个 `]`，正确返回 `ERROR` 和 `api`。

还有一点要注意：VERBOSE 模式会忽略空白，所以日期和时间之间的空格必须写成 `\ `。

**检查：**在 REPL 里对第一行运行 `LINE.match(...)`，调用 `.groupdict()`，确认 `level` 是 `ERROR`。然后再试试上面那行消息里带方括号的日志。

## 第 2 步：把 traceback 归到正确的错误上

`groupdict()` 会以字典形式返回所有命名分组，正好用来把一行日志变成一条记录。凡是匹配不上模式的行，都当作上一条记录的延续：

```python
def parse(path):
    records = []
    with open(path, encoding="utf-8") as f:
        for raw in f:
            line = raw.rstrip("\n")
            m = LINE.match(line)
            if m:
                rec = m.groupdict()
                rec["trace"] = []
                records.append(rec)
            elif records:
                records[-1]["trace"].append(line)
    return records
```

**检查：**示例文件有 11 行，但应该得到 5 条记录，job 5521 和 5530 对应的记录各有一个三行长的 `trace`。如果超过 5 条，说明正则误匹配了 traceback 行。

## 第 3 步：先归一化，再计数

这一步决定了整张结果表。`re.sub` 默认替换模式的所有出现，除非传入 `count` 参数，所以每条规则只需调用一次：

```python
RULES = [
    (re.compile(r"0x[0-9a-fA-F]+"), "<HEX>"),
    (re.compile(r"\d+"), "<NUM>"),
]

def normalize(text):
    for pat, placeholder in RULES:
        text = pat.sub(placeholder, text)
    return text

def signature(rec):
    sig = normalize(rec["msg"])
    if rec["trace"]:
        sig += " | " + normalize(rec["trace"][-1].strip())
    return sig
```

规则的顺序很重要：如果先替换数字，`0x7f3a` 会变成 `xfa`，HEX 规则就什么也抓不到了。这一步之后，示例文件里的两行超时日志都会变成 `Timeout calling bank API order= after ms`。

第 2 步归并的 traceback 在这里派上了用场。在示例文件中，“Failed to process job”这条消息并没有说明任务为什么失败，原因在 traceback 的最后一行：`KeyError: 'customer_id'`。

把这一行追加到签名里，两个 worker 错误就变成 `Failed to process job  | KeyError: 'customer_id'`。以后同样的消息如果带着不同的异常出现，会单独成组，不会被混在一起。

用示例文件算一笔账。直接统计时，四行 ERROR 产生四个分组，各出现一次，什么也看不出来。归一化之后只有两个分组，各出现两次。换成几万行的真实日志，这个差别就是一张无用的表和一份待修复清单之间的差别。

**要点:** 不要统计错误消息本身。去掉所有可变部分之后，统计它们的“形状”。

## 第 4 步：排序，并标出每个错误从哪里、何时开始

`Counter` 是 dict 的子类，用于统计可哈希对象，而签名字符串是可哈希的。`most_common(n)` 返回出现最多的 n 个元素及其次数，按从多到少排列。脚本在计数的同时，还会记下每个签名最早的时间戳，以及那次出现时的 logger：

```python
if __name__ == "__main__":
    records = parse("app.log")
    errors = [r for r in records if r["level"] in ("ERROR", "CRITICAL")]
    counts = Counter()
    first = {}
    for r in errors:
        sig = signature(r)
        counts[sig] += 1
        if sig not in first or r["ts"] < first[sig][0]:
            first[sig] = (r["ts"], r["logger"])
    for sig, n in counts.most_common(10):
        ts, logger = first[sig]
        print(f"{n:>6}  {ts}  [{logger}]  {sig}")
```

把 `r["ts"]` 当字符串比较之所以可行，只是因为示例格式从年一直排到秒；如果客户日志的时间记法不同，比较前要先转成 `datetime`。这也是简化版：每个签名只保留首次出现时的 logger，如果同一个错误来自多个 logger，需要另开一个 `Counter` 统计 logger。

运行 `python3 logtop.py`。**检查：**输出应该如下：

```text
     2  2026-11-03 09:14:22  [payments]  Timeout calling bank API order=<NUM> after <NUM>ms
     2  2026-11-03 09:15:02  [worker]  Failed to process job <NUM> | KeyError: 'customer_id'
```

如果看到四行，说明归一化规则没有执行，或者顺序不对。如果 worker 错误分成了两组，检查第 2 步是否把 traceback 归到了正确的记录上。

## 让数字误导你的几个错误

忘写原始字符串是最常见的坑。没有 `r` 前缀时，`\b` 等部分转义序列会先被 Python 解释，正则会悄无声息地匹配错内容，而且不报错。方括号字段保留贪婪模式同样危险，第 1 步里 `[role] [admin]` 那一行就是例子。

更难察觉的是过度归一化。`\d+` 规则会把 `HTTP 502` 和 `HTTP 404` 变成同一个签名，而对客户来说，这是两类截然不同的问题。如果表格顶部的签名看起来过于笼统，下结论之前先打开几条原始记录读一读。

## 手写正则不够用的时候

客户只有一两个服务时，手写规则集很好用。当日志来自几十个格式各异的服务，`RULES` 列表的膨胀速度会超过你的维护速度。这时就该看看 Drain3，一个开源库，能在日志流式输入时从原始日志中学习日志模板。

Drain 的思路和你刚写的代码很接近。算法把学到的模式存放在一棵解析树中，把不匹配的 token 替换为通配符 `<*>`，就像 `` 代替订单号一样。

Drain3 文档还建议只输入自由文本部分，不带时间戳或主机名，所以第 1 步的正则依然有用，可以先把 `msg` 字段切出来。

## 把 Top 错误表带进会议

第一次会面时手里有一张 Top 10 错误表，开场就有具体的内容可讲：这个错误出现最多，来自这个 logger，从这个时间开始，根因在 traceback 的最后一行。脚本要写成只需改文件路径和行正则就能复用，因为每个客户的日志格式都不一样。

如果你的目标是 FDE 岗位，把脚本连同一份脱敏的示例日志放到 GitHub 上，并在简历里用结果来描述它：处理了多少行日志，归一化前后各有多少个错误分组。

看招聘启事时，留意那些提到处理生产事故或客户问题的条目：面试时正好可以拿出这个工具来讲。

下次客户发来几百 MB 的日志文件，附一句“系统特别慢”，第二次通话开始之前，你就已经能用数字给出答案。

**本周动手试试:**

- 从手头的项目里拿一份真实日志，运行本指南的脚本，记下 Top 10 错误签名。
- 新增一条归一化规则（比如针对 UUID 或邮箱地址），比较前后的分组数量。
- 把脚本封装成接收文件路径的命令行工具，连同一份脱敏的示例日志放到 GitHub 上。

## 信源

- [Regular expression HOWTO — Python 3.15.2 documentation](https://docs.python.org/3/howto/regex.html)

- [re — Regular expression operations — Python 3.15.2 documentation](https://docs.python.org/3/library/re.html)

- [collections — Container datatypes — Python documentation](https://docs.python.org/3/library/collections.html)

- [Logging HOWTO — Python 3.15.2 documentation](https://docs.python.org/3/howto/logging.html)

- [logpai/Drain3 (GitHub)](https://github.com/logpai/Drain3)

- [Drain: simgple but effective log parsing algorithm](https://martinlwx.github.io/en/log-parsing-algorithm-drain/)
