Python heapq 统计日志 TopK 实战：大文件里找出高频接口

线上接口访问日志一多，最常见的问题不是“怎么读文件”，而是“怎么在不把内存撑爆的前提下，快速找出访问次数最高的接口”。这类需求可以先不用上复杂平台，Python 标准库里的 Counter 和 heapq 就能完成一个轻量、可复用的 TopK 统计脚本。

本文用一个简化的 Nginx 风格访问日志做示例，目标是统计请求路径出现次数，并输出访问量最高的前 N 个接口。

适合人群

适合正在用 Python 做日志分析、运维辅助脚本、数据清洗小工具的同学。你只需要了解文件读取、字典计数和基础函数封装。

目录

• 为什么 TopK 不建议直接全量排序
• 逐行读取日志并提取接口路径
• 用 Counter 聚合次数，再用 heapq 取前 N 名
• 常见坑位和线上使用建议

为什么 TopK 不建议直接全量排序

如果日志只有几千行，先统计再排序当然没问题。但日志一旦变成几十万、几百万行，问题会出在两个地方：一是一次性读入文件会占用大量内存，二是对所有接口全量排序并不总是必要，因为我们通常只关心前 10、前 50 或前 100。

更稳的思路是：日志逐行读取，路径逐条计数，最后只从统计结果里拿出前 N 个。heapq.nlargest() 内部会用堆结构维护候选结果，当 N 明显小于总接口数时，代码可读性和效率都更合适。

逐行读取日志并提取接口路径

先看一份简化日志，每行包含请求方法和路径：

10.0.0.1 - - [13/Jun/2026:16:20:01 +0800] "GET /api/orders?page=1 HTTP/1.1" 200
10.0.0.2 - - [13/Jun/2026:16:20:02 +0800] "POST /api/login HTTP/1.1" 200
10.0.0.3 - - [13/Jun/2026:16:20:03 +0800] "GET /api/orders?page=2 HTTP/1.1" 200

统计接口热度时，通常不希望查询参数影响结果，所以 /api/orders?page=1 和 /api/orders?page=2 应该归并为 /api/orders。

from urllib.parse import urlsplit


def parse_path(line: str) -> str | None:
    parts = line.split('"')
    if len(parts) 

这里没有追求复杂正则，而是利用双引号先拿出请求行，再拆出路径。这样写的好处是容易排查：格式不符合预期时直接返回 None，不会让整批统计中断。

用 Counter 聚合次数，再用 heapq 取前 N 名

接下来把读取、计数和 TopK 输出组合起来。注意这里使用文件迭代器逐行处理，不需要一次性把日志读进列表。

from collections import Counter
from heapq import nlargest
from pathlib import Path


def top_paths(log_file: str, limit: int = 10) -> list[tuple[str, int]]:
    counts: Counter[str] = Counter()

    with Path(log_file).open("r", encoding="utf-8", errors="replace") as handle:
        for line in handle:
            path = parse_path(line)
            if path is None:
                continue
            counts[path] += 1

    return nlargest(limit, counts.items(), key=lambda item: item[1])


if __name__ == "__main__":
    for path, total in top_paths("access.log", limit=5):
        print(f"{total:8d}  {path}")

输出结果大概会像这样：

   18420  /api/orders
   12033  /api/login
    9011  /api/products
    6430  /api/cart
    5102  /api/payments

如果只需要前 5 个接口，没必要把所有接口按访问量完整排一遍。下面这张图把两种方式放在一起看：左边是全量排序，右边是只维护候选 TopK。

常见坑位和线上使用建议

1. 查询参数要不要保留

如果你排查的是接口热度，建议去掉查询参数；如果你排查的是某个搜索词或筛选条件导致的压力，就可以把指定参数保留下来单独统计。

2. 状态码是否要参与筛选

排查故障时，最好先按状态码过滤。例如只统计 5xx 请求，可以在 parse_path() 外再写一个 parse_status()，把成功请求和失败请求拆开看。

3. 多个日志文件如何处理

可以让函数接收文件列表，把多个文件的计数累加到同一个 Counter 里。只要仍然逐行读取，就不会因为文件数量增加而突然占用大量内存。

4. TopK 不是越大越好

如果 limit 设置得接近接口总数，堆筛选的优势会下降。日常排查建议先取前 20 或前 50，确认热点方向后再做更细的分组分析。

小结

这套脚本的核心链路很简单：逐行读取日志，提取稳定的接口路径，用 Counter 聚合次数，再用 heapq.nlargest() 输出 TopK。它适合临时排查接口热点、访问倾斜和异常流量，也方便继续扩展状态码过滤、时间窗口统计、多个文件合并等能力。