为什么我用 Vector+logrotate 管理 API 和消费者日志
消费者日志进入 API 文件、多副本共写文件、日志过大触发服务器报警,以及格式不统一,促使我重新整理主业务日志链路。本文记录应用结构化输出、Vector 分类落盘、机构文本视图与 logrotate 文件管理的分工,并交代当前覆盖范围和取舍。
这次整理主业务 API 和消费者的日志,起点是四个反复出现的问题:日志归属混乱、多副本共写文件、文件经常过大,以及输出格式不统一。
过去,消费者调用共用业务模块后,一部分日志仍然进入 API 侧的文件输出。多个机构共享消费者时,也很难直接查看某个机构的处理过程。多副本写同一个日志文件又带来了并发管理问题,过大的日志文件还经常触发服务器报警。
因此,我逐步重新划分了职责:应用输出结构化日志,Vector 负责解析、分类和落盘,logrotate 负责文件轮转、压缩与保留。
本文讨论的是主业务 API 和已接入的 Python/Go 消费者。其他后端项目的接入情况,需要分别核对,不能仅凭这一份配置就认为已经全部覆盖。
一、先解决日志究竟属于谁
最先影响排查体验的,是消费者日志和 API 日志混在一起。
这里需要准确解释“冒泡”。Python 日志会在当前进程的 logger 层级中传播,交给相应 handler 输出。它不会跨进程跳进另一个 API 服务。
旧配置中,部分业务 logger 显式绑定了 API 侧的文件 handler,或者沿用了共用配置。消费者调用这些模块后,即使配置了自己的 root logger,命名 logger 上残留的文件 handler 仍可能继续写入原来的文件。
因此,只在消费者入口再配置一个 logger,并不能自动整理所有业务模块的输出归属。
当前处理会先清除业务命名空间中旧的显式 handler,再让日志传播到当前消费者进程的 root,由该进程的统一出口处理。propagate 仍然可以使用,关键是传播到哪里,以及那里挂着哪些 handler。
这一步也说明,接入 Vector 之前,应用自身的日志配置仍然要整理。采集器可以根据字段分类,却不能替应用判断某个残留的文件 handler 是否应该存在。
二、应用副本输出日志,采集层管理最终文件
多副本共写同一个文件,需要管理的不只是追加内容。
轮转时,写入方可能继续持有原文件句柄;不同进程也可能分别尝试重命名、压缩和清理同一组文件。每个应用副本都维护一套文件生命周期逻辑,配置与并发关系就会越来越难核对。
Python 标准日志支持单进程内的多线程使用,但标准文件 handler 并不提供通用的跨进程文件写入协调。相关背景可参考 Python Logging Cookbook。
新的主链路是:
应用输出单行 JSON
→ stdout/stderr
→ Docker 容器日志
→ Vector 解析、标准化与分流
→ 可读文本 .log +结构化 .jsonl
→ 宿主机 logrotate 管理落盘文件
应用副本不用直接争用最终日志文件,也不用各自轮转同一个文件。当前部署由宿主机上运行的 Vector 容器负责输出目录,文件写入归属更加明确。
这个边界仍然需要在部署时保持。如果把多个采集器指向同一输出文件,仍然要重新考虑文件所有权,不能因为使用了 Vector 就认定任意并发写入方式都安全。
三、统一格式,同时保留不同链路的上下文
另一项改动,是先统一应用输出,再由采集层生成适合不同用途的文件。
应用输出结构化 JSON,保留时间、等级、服务名称、服务类型和业务字段。Vector 接收 Docker 日志后解析这些字段,补齐通用信息,再按服务和日志类别路由。当前采集入口有明确白名单,新服务需要接入对应规则。Vector Docker 日志源提供了这类采集能力。
API 日志主要围绕一次请求定位,关注请求标识、路径、状态码、耗时,以及可用的用户和机构上下文。当前分类为访问日志 access 和应用日志 app,分别输出到自己的文本与 JSONL 文件。
这两类是职责分类,不能简单理解成普通日志与错误日志。
消费者的关注对象则是任务和消息。除了服务名称,还需要记录处理阶段、机构、文章,以及 Kafka 的 topic、partition、offset 等信息。遇到某篇文章处理异常时,才能沿这些字段继续定位。
机构和文章信息需要由应用在处理消息时提供。Python 通过任务上下文绑定并在结束后恢复,Go 则可以在对应 logger 中附加业务字段。Vector 使用已经收到的字段分流,不会凭空知道一条记录属于哪个机构。
最终保留两种输出:.log 方便直接阅读,.jsonl 保留结构化信息,便于程序过滤或后续采集。它们来自同一条应用记录,避免每种服务分别维护两套最终文件格式。Vector 文件输出说明介绍了相关输出方式。
四、为单个机构提供更聚焦的日志视图
多个机构共享消费者时,总日志中的业务记录会交错出现。只想查看一个机构的处理情况时,需要不断筛选,观察一次完整过程不够直观。
因此,我为部分消费者增加了按机构划分的文本文件。以实时聚类消费者为例,目录可以这样理解,机构 ID 使用匿名示意:
logs/
api/
access.log
access.jsonl
app.log
app.jsonl
social_realtime_clustering_consumer/
consumer.log
consumer.jsonl
by_customer/
org-a.log
org-b.log
default.log
总文件继续保留整个消费者的运行情况,机构文件则提供一个额外的排查入口。启动、调度等没有机构上下文的记录进入 default.log,不会为了分机构而丢掉这些信息。
当前按机构生成的是文本副本,并没有移除服务总日志,也不是机构级 JSONL。它会增加存储量,价值是让单机构排查更加直接;文件划分本身也不等于访问权限隔离。
这项配置目前覆盖预处理、实时聚类、pending、风险重算、热榜关键词、热榜事件、统一事件关键词和统一事件这八类 Python 消费链路。
其他消费者需要按实际配置描述。Go 手动关键词、相关性和专题聚类等消费者当前主要保留服务总文件;统一文章消费者则按 Compose project 输出文件,不能把这些情况都写成已经按机构拆分。
五、让 logrotate 统一管理轮转、压缩和保留
日志文件经常过大并触发服务器报警,也是这次改造的直接原因之一。
文件由采集层生成后,我将轮转和保留交给宿主机 logrotate。当前配置包含 daily、rotate 7、compress、dateext、copytruncate 和 maxsize 2048M。
这些配置应当按实际含义理解:按天判断轮转,保留七份轮转档并压缩;大小条件在 logrotate 被调度执行时检查。它不是持续运行的文件大小控制器,不能把配置写成文件绝不会超过 2GB,也不能无条件把七份轮转档等同于严格七天。
当前 copytruncate 会先复制日志,再原地截断原文件。写入方可以继续使用原来的文件,因此不依赖通知 Vector 重新打开文件。
这个选择有取舍:复制与截断之间存在一个可能丢失新写入内容的小窗口。该模式下,配置中的 create 也不负责创建新的当前文件。具体行为可参考 logrotate 官方手册。
此外,Docker 原始容器日志有自己的驱动和保留配置,logrotate 管理的是 Vector 输出文件。原始日志、总文本、JSONL 和机构副本都需要纳入存储考虑,不能只限制其中一层就认为整体增长已经得到控制。
六、排查入口清楚了,仍然需要保留实际边界
这次调整的收益,首先是职责更加清楚。
查接口请求时,从 API 访问日志进入,再结合请求标识查应用处理;查消费任务时,先确定消费者和业务对象,再按机构、文章或 Kafka 坐标缩小范围。需要观察服务整体状态时,仍然可以回到总日志。
这些入口依赖统一上下文和分类规则,而不是只依赖一条包含大量文字的 message。
当前方案也保留其他用途的出口。Python 仍有可配置的 ES 错误上报,本地开发可以使用 local_text 模式;可见的 Vector 配置主要输出本地文件,不能仅凭下游规划就认为已经完成全部云日志接入。
应用配置、Docker 原始日志、Vector 分类和 logrotate 调度,需要分别验证。正常输出之外,还应核对异常记录、缺少机构字段的记录,以及轮转前后的实际文件行为。
对我现在的排查流程而言,最直接的变化是有了明确的查找顺序:先找到服务和阶段,再缩小到业务对象或机构,最后根据保留的上下文继续追踪。日志增长则由独立的文件管理规则维护,不再分散到每个应用副本中重复处理。
记录过程,也留下判断。
← 继续阅读其他文章