先说结论rea 是我用两个周末写出来的一个实时事件分析小工具项目代号就叫 rea全称是 Real-time Event Analyzer。它解决的是我日常工作中最烦的一个问题线上出状况的时候明明有海量日志却很难快速得到“最近 5 分钟到底发生了什么”的答案。如果你也经常在终端里 grep 日志、用 awk 凑统计或者临时写一段 Python 脚本去数错误码那这篇文章对你应该有点用。rea 不是一个大数据平台它更像一把“事件流瑞士军刀”读取日志文件或标准输入把非结构化的文本解析成结构化事件然后在时间窗口里做聚合统计最后输出成表格、JSON或者直接推给监控系统。它适合后端开发、运维、SRE也适合所有需要在命令行里快速分析日志的人。整个项目只有两个核心文件、一个 YAML 配置入口依赖全是 Python 标准库单机就能跑没有 agent不用部署服务。这篇文章我会从背景、设计、实操到排障完整复盘一遍包括我为什么没有选 Flink 和 Kafka Streams、Nginx 日志实时统计的完整配置、以及我踩过的几个坑。如果你也想做一个类似的小工具或者只是想把日志分析这件事做得更顺手可以照着下面的思路直接抄。1. 项目背景天天翻日志翻到崩溃1.1 rea 到底是个什么东西rea 的全称是 Real-time Event Analyzer。它的核心定位是“把日志变成可以秒级查询的统计结果”。你不需要写复杂的查询语言也不需要启动任何服务只需要给它一条管道配置它就会按照你定义的方式去读日志、解析字段、聚合数据并持续输出结果。从使用形态上看rea 是一个命令行工具。基本用法是这样tail -f /var/log/nginx/access.log | rea -c nginx.yaml也可以用内置的 tail 模式直接监听文件rea -c nginx.yaml两种方式都会进入一个持续运行的循环每隔几秒刷新一次统计结果。配置里可以指定用什么正则解析日志、按什么时间窗口聚合、聚合哪些指标以及结果往哪里输出。它不试图替代完整的可观测性平台而是填补一个我长期觉得尴尬的空档线下排查、临时观测、快速验证时我不想为了一小段日志去搭一套 Flink也不想等监控面板刷新。1.2 没有它之前我是怎么做日志分析的在没有 rea 之前我处理线上日志大致是这几个路子。第一直接 grep。比如查 500 错误grep HTTP/1.1\ 500 access.log | wc -l。这个方案的问题很明显只能统计固定字符串稍微复杂一点的需求比如“每个接口的 P95 延迟”或者“最近一分钟 5xx 在总请求里的占比”grep 就非常吃力。第二awk 一行流。awk {print $9} access.log | sort | uniq -c | sort -rn。这个能应对简单的字段计数但遇到日志格式变化、时间字段不是第一个、需要做时间窗口截断的时候awk 脚本会越长越复杂最后变成一堆没人能维护的“玩具代码”。第三临时写 Python 脚本。每次都要重新处理读文件、按行切割、正则匹配、聚合这些重复逻辑真正想分析的业务问题反而没时间想。而且临时脚本往往没有统一的时间戳解析换一种日志格式就要重写一大半。我真正想拥有的工具是它已经内置了“读文件、解析、聚合、输出”的完整链路我只需要告诉它“日志长什么样、想统计什么”剩下的重复劳动全部交给它。这就是 rea 的雏形。用它我只需要维护一个 YAML 配置而不是一坨一次性 Python 脚本。2. 核心设计事件流管道2.1 日志行到事件的抽象rea 最基础的设计决策是先把“日志行”抽象成“事件”。日志行是文本事件是结构化数据。举个例子Nginx 一行日志192.168.1.10 - - [05/Jul/2025:14:23:11 0800] GET /api/user HTTP/1.1 200 1024在 rea 内部会被解析成一个字典{ ip: 192.168.1.10, time: datetime(2025, 7, 5, 14, 23, 11, tzinfo...), method: GET, path: /api/user, status: 200, bytes: 1024 }这个抽象是所有后续处理的基础。有了结构化事件聚合逻辑就不需要关心原始日志长什么样只需要对字段做运算。比如统计状态码就是按status字段分组计数统计 P95 延迟就是对latency字段做分位数计算。事件里最重要、也最容易出问题的是时间戳。rea 把它单独拎出来处理每个事件必须有time字段窗口聚合依赖它。如果没有显式配置时间字段rea 会使用“到达时间”也就是数据被读入的时间。对于日志分析场景尽量用日志里的原始时间这一点我在后面排障部分会详细说。2.2 为什么我不用 Flink / Kafka Streams很多人一听到“实时事件分析”第一反应就是上流处理框架。我来说说为什么 rea 刻意绕开了这条路线。Flink 和 Kafka Streams 是完整的分布式流处理平台有状态、有窗口、有精确一次语义功能非常强大。但它们的运维成本也很高需要一个集群需要管理作业提交需要处理 checkpoint对操作人员的要求也不低。我只是想在服务器上快速看一眼日志统计为一个临时需求去部署一套集群属于典型的“杀鸡用牛刀”。Logstash 这类工具也能做数据解析和转发但它的强项是数据管道弱项是聚合计算。我不想为了一个 count 聚合再引入一套 Ruby 生态。而 awk 和 shell 管道灵活有余但表达复杂逻辑很痛苦调试一次正则就要改一次脚本。rea 的设计哲学是“单机可用、配置驱动、足够快”。它假设数据量是一台机器能处理的范围每天几 GB 到几十 GB 日志足够高峰期每秒几千条事件也足够。如果数据量大到单机扛不住那确实该上 Flink但那是另一个量级的问题。作为一个排查工具启动快、修改快、没有外部依赖是远比横向扩展更重要的特性。2.3 管道结构解析rea 的核心是一条管道input - parser - window - aggregate - output。每个环节都是可替换的组件用 YAML 配置串联。input 负责产生原始事件。目前支持 stdin、tail 文件、以及从 HTTP 端点接收 JSON 数据。parser 负责把原始文本转成结构化事件内置了 regex、json、kv 三种解析器。window 负责管理时间窗口支持固定窗口和滑动窗口。aggregate 负责在窗口内做计算支持的算子包括 count、count_by、sum、avg、min、max、p50/p90/p95/p99。output 负责输出结果支持表格、JSON 行、以及 HTTP POST。组件通过一个轻量级队列连接输入侧解析出来的事件都会被推入一个有界队列聚合侧从这个队列消费。如果消费速度跟不上队列会触发背压输入侧暂停读取防止内存无限增长。这个设计和生产级流处理框架的背压机制本质一样只不过实现只有几十行代码。选择这种管道结构是因为它可以被直观地理解。每一阶段只做一件事配置和调试都比较容易。想改解析规则只需要改 parser 段想换输出方式只需要改 output 段。这和 Unix 哲学是一致的小工具、清晰的边界、可组合。3. 安装与第一条命令3.1 环境要求与安装方式rea 的环境要求非常低。Python 3.9 以上即可不需要安装任何第三方依赖。代码拿到手之后直接运行rea.py就行不涉及虚拟环境、编译、服务注册这种东西。我目前的标准安装方式是从仓库拉代码然后把可执行入口软链到~/bin下。为了方便说明我这里用“仓库”代替实际地址git clone https://example.com/rea.git cd rea chmod x rea.py ln -s $(pwd)/rea.py ~/bin/rea rea --version如果你只想临时跑一下也可以不建软链直接用python rea.py执行。整个项目在我机器上占用不到 200KB启动时间大概 0.3 秒这让我愿意频繁地使用它而不是嫌它重。安装之后可以用rea --help查看支持的参数。主要的几个参数包括rea -c config.yaml # 指定配置文件 rea --dry-run # 只解析不聚合用于调试 rea --until-eof # 处理完输入文件后自动退出--until-eof很实用适用于分析历史日志而不是持续 tail 的场景。比如你有一个 1GB 的访问日志想快速统计一下整体情况用这个参数跑完就会自动结束不会在那个终端里一直挂着。3.2 第一个完整配置统计标准输入中的数字为了让你快速理解配置结构我写一个最小示例。假设我们有一个程序会不断输出keyvalue格式的日志比如levelinfo eventrequest process_ms45 levelinfo eventrequest process_ms62 levelerror eventtimeout process_ms5000对应的 rea 配置如下input: type: stdin parser: type: kv timestamp: field: _arrived_at # 不解析日志里的时间使用到达时间 window: type: sliding size: 60 step: 10 aggregate: - metric: request_count op: count filter: event request - metric: avg_process_ms op: avg field: process_ms output: type: table interval: 10跑起来tail -f app.log | rea -c min.yaml你会在终端看到每 10 秒刷新一次的表格里面有最近 60 秒内的request_count和avg_process_ms。这里有两个点我需要解释一下。第一_arrived_at是 rea 的内置字段表示事件进入系统时的系统时间对应“处理时间”语义。第二filter是字符串形式的表达式支持简单的比较和逻辑运算用于在聚合前过滤事件。这个最小配置已经能解决很多问题了。比如你收到一个“服务变慢”的反馈就可以挂着这个工具跑一会儿看avg_process_ms有没有明显上升。不用先写脚本不用开 IDE一条命令搞定。3.3 输出效果与界面rea 的表格输出是主动刷新的。每次输出周期结束它会清空当前终端区域重新绘制一张表。表格的列对应每个聚合指标行对应时间窗口的结束时间。下面是模拟输出窗口截止时间 request_count avg_process_ms 2025-07-05 14:23:10 3285 52.4 2025-07-05 14:23:20 3412 58.1 2025-07-05 14:23:30 2977 63.9如果指标太多表格会自动横向扩展终端不够宽时优先保留最新一列。对于简单场景这个输出已经足够直观。如果你要接监控系统把 output 改成jsonrea 就会每行输出一个 JSON 对象方便下游消费。我第一次跑通这个最小配置的时候最大的感受是原来实时统计分析可以在一个终端里这么轻量地完成。之前我为这个需求写的临时脚本差不多有 80 行还要处理输出格式而 rea 只需要一个 15 行的 YAML 文件。4. 实战Nginx 访问日志实时统计4.1 正则解析器怎么写Nginx 的访问日志是 rea 能发挥最大作用的场景之一因为它的格式相对固定信息密度高而且排查线上问题时经常需要实时看状态码和响应延迟。假设你的 Nginx 日志格式是 combined 加一段响应时间192.168.1.10 - - [05/Jul/2025:14:23:11 0800] GET /api/user HTTP/1.1 200 1024 0.023最后一位0.023是处理耗时单位秒。那么 parser 可以这样写parser: type: regex pattern: (?Pip\S) - - \[(?Ptime[^\]])\] (?Pmethod\S) (?Ppath\S) HTTP/\d\.\d (?Pstatus\d{3}) (?Pbytes\d) (?Platency_sec[\d.]) timestamp: field: time format: %d/%b/%Y:%H:%M:%S %z这里要特别注意的是正则里每个字段的命名。聚合时你会用到这些名字所以最好语义化。time字段是时间戳来源rea 会按照format指定的格式解析它。%z对应时区偏移比如0800解析后事件时间就是带时区的本地时间。如果你有多个日志格式要处理可以定义多个解析器并根据日志内容自动选择。rea 的 parser 配置支持一个简单的match条件比如包含GET /api就用一套正则包含POST就用另一套。不过大多数情况下一个正则就够了多加解析器反而会让配置变得难读。4.2 滑动窗口和聚合计算配置好解析器之后接下来是最关键的部分选择和计算时间窗口。rea 的滑动窗口由两个参数控制size和step。size是窗口覆盖的时间范围step是输出结果的间隔。比如window: type: sliding size: 60 step: 10意思是每 10 秒计算一次最近 60 秒内的聚合结果。窗口是滑动的每次输出会舍弃窗口外的事件保留窗口内的事件再纳入新到的 10 秒事件。这样你能看到的是“最近一分钟的趋势”而不是一个不断累计的单调计数器。聚合配置可以同时定义多个指标。对于 Nginx 访问日志我通常这样配aggregate: - metric: total_requests op: count - metric: status_5xx op: count_by key: status filter: status 500 - metric: p95_latency_ms op: p95 field: latency_sec - metric: error_rate op: ratio numerator: status 500 denominator: status 0这里p95_latency_ms会把原始字段latency_sec从秒转换成毫秒再排序取分位值。error_rate用两个过滤表达式分别计算分子和分母最终输出一个 0 到 1 的比率。选滑动窗口时有个经验法则窗口大小至少要覆盖你关心的流量波动周期。如果你想监控“最近一分钟的延迟”就用 60如果是看分钟级别的趋势可以设 300 秒窗口、30 秒步长。窗口越大内存占用越高但统计曲线越平滑。4.3 输出到终端和 HTTP统计结果如果只在终端看适合临时排查。但如果你想把它接入公司的监控告警体系最好推送到 HTTP 端点。rea 的 output 可以配置成output: type: http url: https://monitor.example.com/api/v1/metrics method: post headers: Authorization: Bearer your-token format: json interval: 10这样每次窗口滑动结束rea 会组装一个 JSON 数组POST 到指定地址。JSON 的格式大致是{ time: 2025-07-05T14:23:1008:00, window_seconds: 60, metrics: { total_requests: 3285, status_5xx: 12, p95_latency_ms: 210.3, error_rate: 0.0036 } } } 接收端只需要按照这个格式解析就能把实时指标可视化。我在实际使用中会把终端输出和 HTTP 输出同时开启终端用于自己盯着看HTTP 用于通知监控系统。两个输出互相独立任何一个出错不会影响采集主流程。 ## 5. 常见问题与排查技巧实录 ### 5.1 时间戳解析失败 rea 对无法解析时间戳的事件不会静默丢弃而是会在 dry-run 模式下输出警告。常见症状是表格里很多事件的窗口时间都是 1970-01-01或者聚合结果明显偏低好像只统计了一部分数据。 这个问题最常见的根源是正则里的字段名或时间格式写错了。比如 Nginx 日志里的时间字段是 [05/Jul/2025:14:23:11 0800]包含中括号但你在正则里只匹配了括号内的内容没有把 [ 和 ] 排除干净解析出来的字符串就带着多余字符。解决方法是先跑 rea --dry-run它会打印解析出来的完整事件你一眼就能看到 time 字段长什么样。 一个更隐蔽的问题是时区。如果日志时间和系统时区不一致而 time 字段没有 %zrea 会按系统本地时区解释造成结果偏差。我的建议是日志里带时区偏移就一定要放进 format不带时区偏移的在配置里指定 default_timezone: Asia/Shanghai让 rea 统一处理避免混淆。 ### 5.2 聚合结果和实际对不上 有时候你会觉得 rea 统计的请求数比日志文件里 grep 出来的少。这个现象最先让我怀疑的是内部丢数据但排查下来大部分情况是“时间窗口”问题。 如果你用 --until-eof 处理历史日志默认窗口语义是“只统计窗口内的尾部数据”也就是说窗口之前的数据会被丢弃。比如日志文件一共 1000 条跨越 2 小时窗口大小是 60 秒最终只统计最后一分钟的事件。这符合“滑动窗口”的语义但第一次用的人很容易误以为 rea 会统计全量。解决方法是如果你要全量统计把窗口 size 设得比日志时间跨度大或者用 require_complete_window: false 允许不完整窗口输出这样前面的部分也能被计算。 另一个常见情况是日志按时间范围乱序。比如多个文件合并输入时一些事件时间比当前已处理的最大时间还要早。默认情况下窗口会忽略“太旧”的事件避免它们长期占据内存。rea 提供了一个 watermark_lag 参数允许你配置最多容忍多少秒的乱序数据。 ### 5.3 性能问题排查 rea 单机处理能力高不高取决于你的事件大小和解析速度。我实测过比较复杂的正则解析一台普通云主机大约能跑到每秒 2000 到 5000 条。这个量级对日常排障完全够用但如果你想跟踪每秒几万条的高性能网关日志就要注意几个瓶颈。 第一是 input 读取方式。用 tail -f stdin 时rea 本身不管理文件位置你控制不了回放容易受终端管道缓冲影响。用内置的文件 tail 模式可以配置 read_buffer 的大小提高读取效率。第二是正则表达式。复杂的回溯会在高并发场景下拖垮 CPU建议用非贪婪匹配避免 (.*) 这种写法。第三是窗口内存。事件在窗口内都以 Python 字典形式驻留比较占内存。一个粗略的估算公式是每秒事件数 × 事件大小 × 窗口秒数。比如每秒 5000 条、每个事件 1KB、窗口 60 秒那就是 300MB这个量级还在可控范围内。 如果内存不够可以减小窗口或开启 field_projection只保留聚合需要的字段丢弃其余字段。比如你只统计状态码和延迟就不需要保留 ip、user_agent 这些字段能省下一半内存。 ## 6. 踩坑心得与后续计划 ### 6.1 我在实际使用中最深刻的三个体会 第一个体会是不要过度设计。rea 最早版本我写过插件系统、动态加载、分布式支持后来发现这些全部是伪需求。真实需求就是把日志赶紧看明白。删掉那些花架子之后代码量少了三分之一稳定性和可维护性反而提升了。 第二个体会是时间处理永远是事件系统的核心难点。处理时间、事件时间、乱序、时区、夏令时每一个概念都能坑人。我在做过一轮重构后把时间相关逻辑全部收敛到 timestamp 模块里统一用带时区的 datetime避免到处散落 time.time() 调用。如果你要写类似工具建议第一天就这么做。 第三个体会是配置密度太高不见得是好事。YAML 虽然可读性强但一旦嵌套层次超过三层新手就很容易迷路。我后来把配置文件拆成多个文件用 include 语法引用让每个文件只负责一段独立的管道排查问题时能快速定位。这也是 rea 目前配置设计的改进方向。 ### 6.2 后面我想给 rea 加什么 后续计划不多但都来自实际使用中的痛点。第一加一个简单的规则告警插件当某个指标超过阈值时在终端输出颜色告警同时支持输出到文件。第二做一个更完善的消息触达机制比如通过命令行直接调用外部脚本这样我可以收到钉钉或企业微信通知。第三把正则解析的缓存做起来避免同一条日志被重复编译正则表达式进一步提升大文件处理速度。 如果你也想做一个类似的日志分析小工具我的建议是别一开始就奔着“平台化”去先用一条命令解决你手头最痛的那个问题然后在真实使用里慢慢打磨。rea 就是这么从一个 20 行的 awk 临时命令变成一个我自己每天都在用的正式项目的。
先说结论rea 是我用两个周末写出来的一个实时事件分析小工具项目代号就叫 rea全称是 Real-time Event Analyzer。它解决的是我日常工作中最烦的一个问题线上出状况的时候明明有海量日志却很难快速得到“最近 5 分钟到底发生了什么”的答案。如果你也经常在终端里 grep 日志、用 awk 凑统计或者临时写一段 Python 脚本去数错误码那这篇文章对你应该有点用。rea 不是一个大数据平台它更像一把“事件流瑞士军刀”读取日志文件或标准输入把非结构化的文本解析成结构化事件然后在时间窗口里做聚合统计最后输出成表格、JSON或者直接推给监控系统。它适合后端开发、运维、SRE也适合所有需要在命令行里快速分析日志的人。整个项目只有两个核心文件、一个 YAML 配置入口依赖全是 Python 标准库单机就能跑没有 agent不用部署服务。这篇文章我会从背景、设计、实操到排障完整复盘一遍包括我为什么没有选 Flink 和 Kafka Streams、Nginx 日志实时统计的完整配置、以及我踩过的几个坑。如果你也想做一个类似的小工具或者只是想把日志分析这件事做得更顺手可以照着下面的思路直接抄。1. 项目背景天天翻日志翻到崩溃1.1 rea 到底是个什么东西rea 的全称是 Real-time Event Analyzer。它的核心定位是“把日志变成可以秒级查询的统计结果”。你不需要写复杂的查询语言也不需要启动任何服务只需要给它一条管道配置它就会按照你定义的方式去读日志、解析字段、聚合数据并持续输出结果。从使用形态上看rea 是一个命令行工具。基本用法是这样tail -f /var/log/nginx/access.log | rea -c nginx.yaml也可以用内置的 tail 模式直接监听文件rea -c nginx.yaml两种方式都会进入一个持续运行的循环每隔几秒刷新一次统计结果。配置里可以指定用什么正则解析日志、按什么时间窗口聚合、聚合哪些指标以及结果往哪里输出。它不试图替代完整的可观测性平台而是填补一个我长期觉得尴尬的空档线下排查、临时观测、快速验证时我不想为了一小段日志去搭一套 Flink也不想等监控面板刷新。1.2 没有它之前我是怎么做日志分析的在没有 rea 之前我处理线上日志大致是这几个路子。第一直接 grep。比如查 500 错误grep HTTP/1.1\ 500 access.log | wc -l。这个方案的问题很明显只能统计固定字符串稍微复杂一点的需求比如“每个接口的 P95 延迟”或者“最近一分钟 5xx 在总请求里的占比”grep 就非常吃力。第二awk 一行流。awk {print $9} access.log | sort | uniq -c | sort -rn。这个能应对简单的字段计数但遇到日志格式变化、时间字段不是第一个、需要做时间窗口截断的时候awk 脚本会越长越复杂最后变成一堆没人能维护的“玩具代码”。第三临时写 Python 脚本。每次都要重新处理读文件、按行切割、正则匹配、聚合这些重复逻辑真正想分析的业务问题反而没时间想。而且临时脚本往往没有统一的时间戳解析换一种日志格式就要重写一大半。我真正想拥有的工具是它已经内置了“读文件、解析、聚合、输出”的完整链路我只需要告诉它“日志长什么样、想统计什么”剩下的重复劳动全部交给它。这就是 rea 的雏形。用它我只需要维护一个 YAML 配置而不是一坨一次性 Python 脚本。2. 核心设计事件流管道2.1 日志行到事件的抽象rea 最基础的设计决策是先把“日志行”抽象成“事件”。日志行是文本事件是结构化数据。举个例子Nginx 一行日志192.168.1.10 - - [05/Jul/2025:14:23:11 0800] GET /api/user HTTP/1.1 200 1024在 rea 内部会被解析成一个字典{ ip: 192.168.1.10, time: datetime(2025, 7, 5, 14, 23, 11, tzinfo...), method: GET, path: /api/user, status: 200, bytes: 1024 }这个抽象是所有后续处理的基础。有了结构化事件聚合逻辑就不需要关心原始日志长什么样只需要对字段做运算。比如统计状态码就是按status字段分组计数统计 P95 延迟就是对latency字段做分位数计算。事件里最重要、也最容易出问题的是时间戳。rea 把它单独拎出来处理每个事件必须有time字段窗口聚合依赖它。如果没有显式配置时间字段rea 会使用“到达时间”也就是数据被读入的时间。对于日志分析场景尽量用日志里的原始时间这一点我在后面排障部分会详细说。2.2 为什么我不用 Flink / Kafka Streams很多人一听到“实时事件分析”第一反应就是上流处理框架。我来说说为什么 rea 刻意绕开了这条路线。Flink 和 Kafka Streams 是完整的分布式流处理平台有状态、有窗口、有精确一次语义功能非常强大。但它们的运维成本也很高需要一个集群需要管理作业提交需要处理 checkpoint对操作人员的要求也不低。我只是想在服务器上快速看一眼日志统计为一个临时需求去部署一套集群属于典型的“杀鸡用牛刀”。Logstash 这类工具也能做数据解析和转发但它的强项是数据管道弱项是聚合计算。我不想为了一个 count 聚合再引入一套 Ruby 生态。而 awk 和 shell 管道灵活有余但表达复杂逻辑很痛苦调试一次正则就要改一次脚本。rea 的设计哲学是“单机可用、配置驱动、足够快”。它假设数据量是一台机器能处理的范围每天几 GB 到几十 GB 日志足够高峰期每秒几千条事件也足够。如果数据量大到单机扛不住那确实该上 Flink但那是另一个量级的问题。作为一个排查工具启动快、修改快、没有外部依赖是远比横向扩展更重要的特性。2.3 管道结构解析rea 的核心是一条管道input - parser - window - aggregate - output。每个环节都是可替换的组件用 YAML 配置串联。input 负责产生原始事件。目前支持 stdin、tail 文件、以及从 HTTP 端点接收 JSON 数据。parser 负责把原始文本转成结构化事件内置了 regex、json、kv 三种解析器。window 负责管理时间窗口支持固定窗口和滑动窗口。aggregate 负责在窗口内做计算支持的算子包括 count、count_by、sum、avg、min、max、p50/p90/p95/p99。output 负责输出结果支持表格、JSON 行、以及 HTTP POST。组件通过一个轻量级队列连接输入侧解析出来的事件都会被推入一个有界队列聚合侧从这个队列消费。如果消费速度跟不上队列会触发背压输入侧暂停读取防止内存无限增长。这个设计和生产级流处理框架的背压机制本质一样只不过实现只有几十行代码。选择这种管道结构是因为它可以被直观地理解。每一阶段只做一件事配置和调试都比较容易。想改解析规则只需要改 parser 段想换输出方式只需要改 output 段。这和 Unix 哲学是一致的小工具、清晰的边界、可组合。3. 安装与第一条命令3.1 环境要求与安装方式rea 的环境要求非常低。Python 3.9 以上即可不需要安装任何第三方依赖。代码拿到手之后直接运行rea.py就行不涉及虚拟环境、编译、服务注册这种东西。我目前的标准安装方式是从仓库拉代码然后把可执行入口软链到~/bin下。为了方便说明我这里用“仓库”代替实际地址git clone https://example.com/rea.git cd rea chmod x rea.py ln -s $(pwd)/rea.py ~/bin/rea rea --version如果你只想临时跑一下也可以不建软链直接用python rea.py执行。整个项目在我机器上占用不到 200KB启动时间大概 0.3 秒这让我愿意频繁地使用它而不是嫌它重。安装之后可以用rea --help查看支持的参数。主要的几个参数包括rea -c config.yaml # 指定配置文件 rea --dry-run # 只解析不聚合用于调试 rea --until-eof # 处理完输入文件后自动退出--until-eof很实用适用于分析历史日志而不是持续 tail 的场景。比如你有一个 1GB 的访问日志想快速统计一下整体情况用这个参数跑完就会自动结束不会在那个终端里一直挂着。3.2 第一个完整配置统计标准输入中的数字为了让你快速理解配置结构我写一个最小示例。假设我们有一个程序会不断输出keyvalue格式的日志比如levelinfo eventrequest process_ms45 levelinfo eventrequest process_ms62 levelerror eventtimeout process_ms5000对应的 rea 配置如下input: type: stdin parser: type: kv timestamp: field: _arrived_at # 不解析日志里的时间使用到达时间 window: type: sliding size: 60 step: 10 aggregate: - metric: request_count op: count filter: event request - metric: avg_process_ms op: avg field: process_ms output: type: table interval: 10跑起来tail -f app.log | rea -c min.yaml你会在终端看到每 10 秒刷新一次的表格里面有最近 60 秒内的request_count和avg_process_ms。这里有两个点我需要解释一下。第一_arrived_at是 rea 的内置字段表示事件进入系统时的系统时间对应“处理时间”语义。第二filter是字符串形式的表达式支持简单的比较和逻辑运算用于在聚合前过滤事件。这个最小配置已经能解决很多问题了。比如你收到一个“服务变慢”的反馈就可以挂着这个工具跑一会儿看avg_process_ms有没有明显上升。不用先写脚本不用开 IDE一条命令搞定。3.3 输出效果与界面rea 的表格输出是主动刷新的。每次输出周期结束它会清空当前终端区域重新绘制一张表。表格的列对应每个聚合指标行对应时间窗口的结束时间。下面是模拟输出窗口截止时间 request_count avg_process_ms 2025-07-05 14:23:10 3285 52.4 2025-07-05 14:23:20 3412 58.1 2025-07-05 14:23:30 2977 63.9如果指标太多表格会自动横向扩展终端不够宽时优先保留最新一列。对于简单场景这个输出已经足够直观。如果你要接监控系统把 output 改成jsonrea 就会每行输出一个 JSON 对象方便下游消费。我第一次跑通这个最小配置的时候最大的感受是原来实时统计分析可以在一个终端里这么轻量地完成。之前我为这个需求写的临时脚本差不多有 80 行还要处理输出格式而 rea 只需要一个 15 行的 YAML 文件。4. 实战Nginx 访问日志实时统计4.1 正则解析器怎么写Nginx 的访问日志是 rea 能发挥最大作用的场景之一因为它的格式相对固定信息密度高而且排查线上问题时经常需要实时看状态码和响应延迟。假设你的 Nginx 日志格式是 combined 加一段响应时间192.168.1.10 - - [05/Jul/2025:14:23:11 0800] GET /api/user HTTP/1.1 200 1024 0.023最后一位0.023是处理耗时单位秒。那么 parser 可以这样写parser: type: regex pattern: (?Pip\S) - - \[(?Ptime[^\]])\] (?Pmethod\S) (?Ppath\S) HTTP/\d\.\d (?Pstatus\d{3}) (?Pbytes\d) (?Platency_sec[\d.]) timestamp: field: time format: %d/%b/%Y:%H:%M:%S %z这里要特别注意的是正则里每个字段的命名。聚合时你会用到这些名字所以最好语义化。time字段是时间戳来源rea 会按照format指定的格式解析它。%z对应时区偏移比如0800解析后事件时间就是带时区的本地时间。如果你有多个日志格式要处理可以定义多个解析器并根据日志内容自动选择。rea 的 parser 配置支持一个简单的match条件比如包含GET /api就用一套正则包含POST就用另一套。不过大多数情况下一个正则就够了多加解析器反而会让配置变得难读。4.2 滑动窗口和聚合计算配置好解析器之后接下来是最关键的部分选择和计算时间窗口。rea 的滑动窗口由两个参数控制size和step。size是窗口覆盖的时间范围step是输出结果的间隔。比如window: type: sliding size: 60 step: 10意思是每 10 秒计算一次最近 60 秒内的聚合结果。窗口是滑动的每次输出会舍弃窗口外的事件保留窗口内的事件再纳入新到的 10 秒事件。这样你能看到的是“最近一分钟的趋势”而不是一个不断累计的单调计数器。聚合配置可以同时定义多个指标。对于 Nginx 访问日志我通常这样配aggregate: - metric: total_requests op: count - metric: status_5xx op: count_by key: status filter: status 500 - metric: p95_latency_ms op: p95 field: latency_sec - metric: error_rate op: ratio numerator: status 500 denominator: status 0这里p95_latency_ms会把原始字段latency_sec从秒转换成毫秒再排序取分位值。error_rate用两个过滤表达式分别计算分子和分母最终输出一个 0 到 1 的比率。选滑动窗口时有个经验法则窗口大小至少要覆盖你关心的流量波动周期。如果你想监控“最近一分钟的延迟”就用 60如果是看分钟级别的趋势可以设 300 秒窗口、30 秒步长。窗口越大内存占用越高但统计曲线越平滑。4.3 输出到终端和 HTTP统计结果如果只在终端看适合临时排查。但如果你想把它接入公司的监控告警体系最好推送到 HTTP 端点。rea 的 output 可以配置成output: type: http url: https://monitor.example.com/api/v1/metrics method: post headers: Authorization: Bearer your-token format: json interval: 10这样每次窗口滑动结束rea 会组装一个 JSON 数组POST 到指定地址。JSON 的格式大致是{ time: 2025-07-05T14:23:1008:00, window_seconds: 60, metrics: { total_requests: 3285, status_5xx: 12, p95_latency_ms: 210.3, error_rate: 0.0036 } } } 接收端只需要按照这个格式解析就能把实时指标可视化。我在实际使用中会把终端输出和 HTTP 输出同时开启终端用于自己盯着看HTTP 用于通知监控系统。两个输出互相独立任何一个出错不会影响采集主流程。 ## 5. 常见问题与排查技巧实录 ### 5.1 时间戳解析失败 rea 对无法解析时间戳的事件不会静默丢弃而是会在 dry-run 模式下输出警告。常见症状是表格里很多事件的窗口时间都是 1970-01-01或者聚合结果明显偏低好像只统计了一部分数据。 这个问题最常见的根源是正则里的字段名或时间格式写错了。比如 Nginx 日志里的时间字段是 [05/Jul/2025:14:23:11 0800]包含中括号但你在正则里只匹配了括号内的内容没有把 [ 和 ] 排除干净解析出来的字符串就带着多余字符。解决方法是先跑 rea --dry-run它会打印解析出来的完整事件你一眼就能看到 time 字段长什么样。 一个更隐蔽的问题是时区。如果日志时间和系统时区不一致而 time 字段没有 %zrea 会按系统本地时区解释造成结果偏差。我的建议是日志里带时区偏移就一定要放进 format不带时区偏移的在配置里指定 default_timezone: Asia/Shanghai让 rea 统一处理避免混淆。 ### 5.2 聚合结果和实际对不上 有时候你会觉得 rea 统计的请求数比日志文件里 grep 出来的少。这个现象最先让我怀疑的是内部丢数据但排查下来大部分情况是“时间窗口”问题。 如果你用 --until-eof 处理历史日志默认窗口语义是“只统计窗口内的尾部数据”也就是说窗口之前的数据会被丢弃。比如日志文件一共 1000 条跨越 2 小时窗口大小是 60 秒最终只统计最后一分钟的事件。这符合“滑动窗口”的语义但第一次用的人很容易误以为 rea 会统计全量。解决方法是如果你要全量统计把窗口 size 设得比日志时间跨度大或者用 require_complete_window: false 允许不完整窗口输出这样前面的部分也能被计算。 另一个常见情况是日志按时间范围乱序。比如多个文件合并输入时一些事件时间比当前已处理的最大时间还要早。默认情况下窗口会忽略“太旧”的事件避免它们长期占据内存。rea 提供了一个 watermark_lag 参数允许你配置最多容忍多少秒的乱序数据。 ### 5.3 性能问题排查 rea 单机处理能力高不高取决于你的事件大小和解析速度。我实测过比较复杂的正则解析一台普通云主机大约能跑到每秒 2000 到 5000 条。这个量级对日常排障完全够用但如果你想跟踪每秒几万条的高性能网关日志就要注意几个瓶颈。 第一是 input 读取方式。用 tail -f stdin 时rea 本身不管理文件位置你控制不了回放容易受终端管道缓冲影响。用内置的文件 tail 模式可以配置 read_buffer 的大小提高读取效率。第二是正则表达式。复杂的回溯会在高并发场景下拖垮 CPU建议用非贪婪匹配避免 (.*) 这种写法。第三是窗口内存。事件在窗口内都以 Python 字典形式驻留比较占内存。一个粗略的估算公式是每秒事件数 × 事件大小 × 窗口秒数。比如每秒 5000 条、每个事件 1KB、窗口 60 秒那就是 300MB这个量级还在可控范围内。 如果内存不够可以减小窗口或开启 field_projection只保留聚合需要的字段丢弃其余字段。比如你只统计状态码和延迟就不需要保留 ip、user_agent 这些字段能省下一半内存。 ## 6. 踩坑心得与后续计划 ### 6.1 我在实际使用中最深刻的三个体会 第一个体会是不要过度设计。rea 最早版本我写过插件系统、动态加载、分布式支持后来发现这些全部是伪需求。真实需求就是把日志赶紧看明白。删掉那些花架子之后代码量少了三分之一稳定性和可维护性反而提升了。 第二个体会是时间处理永远是事件系统的核心难点。处理时间、事件时间、乱序、时区、夏令时每一个概念都能坑人。我在做过一轮重构后把时间相关逻辑全部收敛到 timestamp 模块里统一用带时区的 datetime避免到处散落 time.time() 调用。如果你要写类似工具建议第一天就这么做。 第三个体会是配置密度太高不见得是好事。YAML 虽然可读性强但一旦嵌套层次超过三层新手就很容易迷路。我后来把配置文件拆成多个文件用 include 语法引用让每个文件只负责一段独立的管道排查问题时能快速定位。这也是 rea 目前配置设计的改进方向。 ### 6.2 后面我想给 rea 加什么 后续计划不多但都来自实际使用中的痛点。第一加一个简单的规则告警插件当某个指标超过阈值时在终端输出颜色告警同时支持输出到文件。第二做一个更完善的消息触达机制比如通过命令行直接调用外部脚本这样我可以收到钉钉或企业微信通知。第三把正则解析的缓存做起来避免同一条日志被重复编译正则表达式进一步提升大文件处理速度。 如果你也想做一个类似的日志分析小工具我的建议是别一开始就奔着“平台化”去先用一条命令解决你手头最痛的那个问题然后在真实使用里慢慢打磨。rea 就是这么从一个 20 行的 awk 临时命令变成一个我自己每天都在用的正式项目的。
