深夜两点被电话叫起来查一个偶发超时登录机器tail -f翻到的那份日志里早就没有出问题的那个时间点了——文件被轮转、压缩、清理一气呵成切到容器里执行logs命令只剩最近十分钟的输出三个副本分散在三台机器上逐个登上去 grep 的效率约等于零。这类场景我经历过不止一次也正是从那时候开始我把实时日志管理从出问题再去翻文件改成了日志持续往外流、随时可检索。标题里提到的这款 Agent就是这条链路最前端的那一环它常驻在机器上盯着你指定的文件把新增的行读出来、拼装、打标签、送到远端。这篇东西写给两类人一类是正准备给项目接入日志采集、但被一堆配置项和多行合并规则绕晕的另一类是已经接入了但总感觉日志好像少了点查出来的时间对不上的。我不会停留在装好就能用这个层面而是把采集端内部那几个真正会出问题的机制拆开讲——文件是怎么被发现的、多行是怎么被拼回去的、缓冲队列在压力下会怎么表现——然后给出可以直接抄的配置和一条完整的排错链路。工具的具体名字不重要各家的采集端在原理上大同小异你把这套逻辑吃透换成任何一个实现都能快速上手。1. 采集端在链路里的真实位置它做的不是收集是流处理前端很多人对采集 Agent 的认知停留在把文件内容发走于是配置的时候就填一个路径、填一个目标地址剩下的交给默认值。这种认知在测试环境完全够用一上生产就会暴露问题明明应用打了日志采集端那边却少了几分钟报错堆栈在界面上变成几十条孤立的单行某台机器 CPU 飙高登录一看是采集进程把内存吃满了。这些都不是工具不好用而是你把一个流处理前端当成了文件拷贝工具。1.1 排查现场失效的三个断点先把痛点摆清楚后面的设计才有依据。第一个断点是时间窗口。本地文件是有生命周期的日志框架按大小或按天轮转运维脚本按保留天数清理一个偶发问题从发生到你开始排查中间可能已经过去了几个小时甚至一天。等你登录机器相关文件要么被压缩成归档包要么已经被删掉。第二个断点是位置分散。现在的服务很少有单实例部署一次请求可能落在任意一个副本上靠人肉逐个登录去 grep成本高到不可接受而且你根本不知道该登哪台。第三个断点是上下文缺失。文件里只有一行行文本谁产生的、哪个环境、哪个版本、哪个请求全靠你自己从内容里猜。采集 Agent 解决的正是这三个断点它把事后找文件变成事中持续搬运把分散在各机器变成汇聚到一处把纯文本变成带标签的结构化记录。理解了这一点你就明白为什么它的配置项里有那么多看起来无关紧要的东西——路径匹配、排除规则、标签注入、解析规则每一项都对应上面某个断点。1.2 从应用写盘到你能搜到中间隔着五道关卡我在给团队做分享时习惯画一张链路图这里用文字描述一条日志从产生到可检索至少要穿过五道关卡每一道都可能丢东西关卡环节典型失效表现常见原因1应用写盘日志根本没落地输出被重定向到 stdout、缓冲区未 flush、日志级别过滤2采集端发现文件新文件长时间没被读取inotify 监听数超限、路径通配符写错、目录权限不足3行读取与合并堆栈被拆成几十条多行规则正则不匹配、规则顺序错误4缓冲与投递高峰期日志延迟或丢失队列满后丢弃策略、网络抖动、批量参数不合理5远端入库与检索搜不到或标签错标签冲突、字段类型不匹配、索引延迟把这五道关卡记住后面任何日志不对劲的问题你都可以按顺序往下切而不是面对一个黑盒瞎猜。我见过太多人一上来就怀疑采集端丢数据最后发现是应用把日志打到了 stdout 而采集端配的是文件路径——第一道关卡就断了。2. 文件发现、多行合并、缓冲投递三个真正决定成败的机制采集端的代码量不大但其中三块逻辑的复杂度远超想象。理解了它们的行为边界你配置的时候就知道哪些默认值不能信哪些参数必须自己算。2.1 文件发现靠的不是遍历目录而是事件监听加轮询兜底多数实现会用操作系统的文件系统事件机制来监听目录变更新文件创建、文件被追加、文件被重命名都能拿到通知。听起来很完美但有两个坑。第一单个进程能监听的目录和文件数量是有上限的容器密度高的机器上光日志目录就能塞进去几千个文件加上应用自身的监听很容易触顶。触顶之后的表现非常隐蔽新创建的文件永远不被读取老文件继续正常采集你在界面上看一切正常只是某几个 Pod 的日志凭空消失了。第二事件机制在某些场景下会漏事件比如网络文件系统、某些容器运行时对日志文件的处理方式、文件被快速创建又重命名。所以成熟的实现都会加一层周期性扫描作为兜底每隔一段时间把目录重新扫一遍看看有没有该采但没在采的文件。这个扫描间隔就是配置项里的scan interval之类的东西默认值往往偏保守。我的经验是把扫描间隔压到 10 秒以内同时观察采集进程的文件描述符数量。日志文件多的时候采集端会同时持有大量打开的文件句柄这时候系统级限制就必须调整否则某个时刻它会因为打不开新文件而静默跳过。这个坑我在一个日志目录挂了几千个文件的机器上踩过表面症状是部分日志延迟两三分钟才出现实际原因是句柄耗尽后进入了缓慢的重试循环。2.2 多行合并一个正则写错报错堆栈就全废了这是采集端最容易被低估的功能也是最容易配错的地方。应用输出的异常堆栈天然是多行的2024-06-11 03:22:17.884 ERROR [order-service,trace9f3a] Request failed java.lang.IllegalStateException: connection pool exhausted at com.example.pool.Pool.borrow(Pool.java:88) at com.example.order.OrderService.place(OrderService.java:142) Caused by: java.net.SocketTimeoutException: Read timed out at com.example.net.Client.read(Client.java:65)默认按行切分的采集端会把它拆成六条独立记录每条都被打上同一个时间戳或者更糟只有第一行有时间戳到了检索端你想看完整链路根本不可能。所以必须在采集配置里声明合并规则以什么模式开头的行是新记录的开始不匹配这个模式的行就追加到上一条。规则看起来简单坑在于三点。一是规则的锚定方式。你要匹配的是时间戳加日志级别这种行首特征如果正则没加行首锚定那么堆栈里出现类似格式的行比如某个异常的 message 里恰好带了时间字符串就会误判为新记录的开始把一条完整的堆栈劈成两半。二是状态机的最长等待。如果某条记录的第一行写出去之后后续行迟迟不来应用卡住了采集端需要有超时机制把它强制刷出去否则这条日志会一直挂在内存里直到超时或者文件被轮转。三是应用自身行为的配合。如果应用是把堆栈直接printStackTrace到标准输出而日志框架又在外面包了一层两条输出流的时序可能交错合并在物理上就不可能正确。这种情况要从应用侧改成一次性输出完整异常字符串而不是指望采集端猜。# 多行合并的常见写法示意字段名以实际实现为准 multiline: # 只有匹配这个模式的行才被认定为一条新日志的开始 start_pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} # 合并状态最多保持多久超时强制刷出防止内存里挂死 flush_after: 2s # 单条记录的最大行数防止某条日志无限膨胀 max_lines: 500max_lines这个上限非常必要。我遇到过一种情况某个依赖库在异常时会把一个巨大的对象toString全打出来单条日志几十万行采集端内存直接翻倍然后被系统的内存限制干掉顺便把同一台机器上其他正常的日志也带走了。设了上限之后超出的部分会被强制断开成新记录虽然不完美但至少不会把采集进程整个拖垮。2.3 缓冲队列背压来了之后数据到底去哪了采集端不可能读到一行就发一次网络请求那样开销太大所以它一定有一个内存队列做削峰。链路是读取线程写队列投递线程批量取出来发送。当远端不可用、或者网络变慢的时候队列开始堆积。这时候的行为取决于两个参数队列容量和满了之后的策略。队列容量决定能扛多久的抖动。假设你的日志量是每秒 2MB队列容量 512MB理论上能缓冲四分多钟的断网。这个数字听着够用但要考虑压缩比——传输前通常会压缩队列里存的可能是压缩后的数据实际能扛的时间更长。反过来如果日志里有大量重复内容压缩率很高你反而可能在内存里堆了远超预期条数的记录。满了之后的策略才是关键。常见有三种阻塞读取对应用侧产生反压日志文件写满磁盘最终影响业务、丢弃新数据队列满之后进来的直接扔、丢弃最旧数据把队头弹掉腾位置。这三种没有绝对优劣取决于你对宁可丢也不能卡业务还是宁可卡也不能丢日志的取舍。我的默认选择是在采集端丢弃并计数配合一个丢弃量的监控指标告警。理由很实在日志服务的可用性不应该高于业务本身但你必须知道丢了而且要知道丢了多少。静默丢弃是最坏的方案。3. 部署形态与标签体系决定了三个月后你还能不能查得到工具装在哪、怎么打标签这两件事在接入当天看起来是形式问题实际上它们决定了这套日志体系半年后是资产还是垃圾。3.1 宿主机守护进程、Sidecar、集群级采集的取舍三种主流形态我用一张表对比这里的结论来自几次不同规模项目的实际选择形态适用场景优势代价宿主机常驻进程传统虚机、物理机部署资源占用低与业务生命周期解耦采集配置集中管理需要单独配路径映射容器化环境下路径不直观每 Pod 一个伴生容器容器化早期、需要按业务定制采集规则隔离性好配置随应用走重启不影响他人资源开销成倍增加Pod 数量大时管理成本高集群级采集按节点部署大规模容器集群一台机器一个采集实例成本最优需要在配置里做大量的路径和元数据自动发现我倾向的选择是集群规模小、业务差异大时用伴生容器集群规模上来之后统一切到节点级采集。中间那个过渡期最难熬两套形态并存标签规则不一致检索的时候要在两套体系之间跳。所以如果预判未来一年 Pod 数量会翻几倍一开始就别选伴生方案直接上节点级省下来的迁移成本远超前期多花的配置时间。节点级采集最大的挑战是元数据自动发现。容器里的日志文件在宿主机上是一层软链接指向某个内部路径文件名是一串随机 ID 加上容器 ID。如果你靠硬编码路径去采容器一重启路径就变了。正确的做法是让采集端从容器运行时或者集群的元数据接口拉取信息把容器 ID 映射成服务名、命名空间、实例等标签。这块配置看起来复杂但它是唯一能长期维护的方案。3.2 标签不是给机器看的是给凌晨三点的你看的我在几个项目里见过的最糟糕的标签设计是所有日志一律打上envprod, appbackend然后靠日志内容里的字符串区分服务。结果是每次排查要写复杂的全文检索条件还得祈祷日志格式一致。标签设计的核心原则是任何你在检索时想用来先缩小范围的维度都必须是一个标签。我的最小标签集是这样的service服务名与部署单元一一对应不做任何缩写env环境取值只用固定的几个枚举不要出现prod、production、prd三种写法instance实例标识能用节点名加序号就别用随机 IDversion构建版本号排查是不是这次发布引入的时是刚需log_type日志类别比如app、access、gc、audit方便分索引和分保留策略前四个是基础第五个往往被忽略但价值很高。访问日志、GC 日志、审计日志的数据量级、保留周期、检索频率完全不同混在一起你只能按最大的那个标准来定保留策略成本白白浪费。分类型之后审计日志可以留一年GC 日志留三天各取所需。还有一个细节标签值的基数。千万别把请求 ID、用户 ID 这类高基数信息打成标签那会让索引端直接崩掉而且检索性能急剧下降。这类信息应该放在日志正文或者结构化字段里而不是标签。我见过一个团队把 trace ID 当标签用一天之内索引分片数暴涨最后不得不重建整个索引。4. 一份能直接跑的配置路径、解析、脱敏逐项拆解配置这块我不打算只给一份模板而是逐项说明为什么这么写。你要能改而不是只能抄。4.1 采集路径与排除规则# 采集端主配置字段名以实际实现为准逻辑通用 sources: - name: app-logs # 用通配符覆盖按天轮转的文件 paths: - /var/log/app/*.log - /var/log/app/*.log.1 # 排除规则必须写否则压缩包和临时文件都会被读 exclude: - /var/log/app/*.gz - /var/log/app/*.tmp - /var/log/app/archive/** # 从文件末尾开始读避免首次启动把历史全量灌进去 start_position: end tags: service: order-api env: prod log_type: app multiline: start_pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} flush_after: 2s max_lines: 500几个点值得单独说。start_position这个选项如果设成从头读第一次启动的时候会把目录下所有历史日志一次性发出去几 GB 的数据瞬间灌进来远端可能直接限流本地队列瞬间打满然后开始丢数据——你会以为是采集端有 bug其实是自己的配置在自助式拒绝服务。反过来设成从末尾读意味着首次启动之前的内容全都不要这在大多数场景没问题但如果你接这套东西的动机就是补一下历史日志那就要在维护窗口里单独处理别指望日常配置兼顾。排除规则那一段最容易被漏掉的是压缩包。日志轮转之后通常会被压缩成.gz如果采集路径用了宽泛的通配符采集端会尝试去读压缩文件读出二进制乱码白白消耗带宽和存储空间还会污染检索结果。.tmp同理有些应用会先写临时文件再重命名读半成品没有意义。归档目录更要排除那是给人手动查的不是给采集端读的。name字段看似无关紧要但它常常是排查配置是否生效的第一入口。给每个来源起一个能一眼看懂的独立名字后面看采集端自身的统计指标时你能立刻定位是哪个来源出问题而不是面对一个整体的已采集字节数发懵。4.2 脱敏、采样与资源天花板日志里带敏感信息是常态手机号、身份证号、令牌、连接串随手一打就进去了。指望开发同学每处都记得脱敏不现实所以在采集端做一层兜底是必要的。# 采集端的过滤与脱敏示意 filters: # 正则替换顺序执行先处理最具体的模式 - type: replace pattern: (?i)(password|token|secret)([^\s]) replacement: $1*** - type: replace pattern: \b1[3-9]\d{9}\b replacement: 1********** # 丢弃健康检查的噪音日志这类日志通常占三成以上 - type: exclude pattern: GET /healthz HTTP/1\.1 200健康检查日志的过滤这一条建议每个项目都加上。我做过的统计里某些服务的健康检查请求能占到总请求数的三到五成这些日志除了占空间没有任何排查价值。过滤掉之后存储成本和检索噪音同时下降收益非常直接。资源天花板必须显式设置。采集进程跑在业务机器上它抢走的每一份 CPU 和内存都是业务的损失。要设置的三项是单文件读取的速率上限防止某个超大日志文件吸干 IO、进程内存上限超过就触发自我保护先丢队列而不是被杀、批量投递的条数和字节数。速率上限这条尤其重要我遇到过一次事故某个调试开关忘了关一个服务的日志输出速度暴涨了几十倍采集端全速读取磁盘 IO 被打满业务请求的超时率跟着上去了。后来加了速率限制超出部分只记录丢弃计数反而更稳。5. 丢日志、重复日志、时间错乱三类故障的完整排查链路这一节是我最想写的部分。日志系统的问题里90% 可以归到这三类而每一类的根因分布都很集中。我把排查顺序写出来你可以照着走。5.1 静默丢日志先查 inode 复用再查轮转现象某个时间段的日志在检索端完全找不到前后时间段正常采集端自身没有报错。排查链路是这样的。第一步确认文件本身在不在。去机器上看那个时间段对应的文件是否还存在如果已经被清理那就是保留策略的问题跟采集端无关得回头调轮转和清理的窗口确保清理之前数据已经搬运完毕。第二步如果文件还在用wc -l数一下总行数再去检索端数同一时间范围的行数差值就是丢的量。第三步看采集端的读取进度记录——多数实现会在本地维护一个偏移量文件记录每个文件读到哪了。如果这个偏移量比文件实际大小还大说明它读到了未来的位置。这就是最隐蔽的那个坑文件轮转之后 inode 被复用。日志文件被重命名新文件被创建如果新文件恰好复用了旧的 inode 编号而采集端的进度记录是按 inode 做索引的它就会认为这个文件我已经读到第 N 字节了于是新文件的前 N 字节被直接跳过一声不吭。这种丢失极其难查因为所有指标都正常只有内容凭空少了。规避方式有两个一是让轮转配置使用复制后截断模式而不是重命名模式代价是一瞬间磁盘占用翻倍二是确保采集端在记录进度时同时校验文件的创建时间或者设备号而不只看 inode。第二种是更根本的方案但取决于实现是否支持选型的时候值得专门问一句。第四步如果偏移量正常那就往上追到文件发现环节检查前面说的监听上限和句柄数。这条我建议做成例行检查定期对比应该存在的日志文件数和采集端实际在采的文件数两个数字对不上就是有问题的前兆。5.2 重复投递的三种真实成因重复日志比丢日志温和但它同样是问题会让统计口径全乱。成因基本就三种。第一种是采集端重启后的重发。为了保证至少一次投递多数实现会在确认远端接收成功之后才推进本地进度。如果进程在发送成功但进度未落盘的窗口里被杀掉重启后会从上次的进度重新读这一段就重复了。这个窗口的大小取决于进度落盘的频率落盘太频繁会影响性能太稀疏会放大重复量。我的经验是把它控制在秒级重复量可以接受因为下游可以用唯一 ID 去重。第二种是同一份日志被多个来源采集。比如你既配了/var/log/app/*.log又配了/var/log/app/order.log那么 order 这个文件会被两条规则同时命中每条日志发两遍。这种重复非常好认——重复的两条在时间上几乎完全一致标签却不同。排查方法就是把所有采集路径列出来两两取交集看有没有包含关系。宽泛通配符和精确路径混用几乎是必踩的坑。第三种是日志被写了两遍。应用配置里同时挂了文件输出和标准输出而采集端两边都在采。这种情况重复的两条内容完全一致、标签完全相同只有采集来源不同。解决办法是从应用侧关掉一条输出路径或者在采集端明确只采其中一条。5.3 时间戳错乱四个来源逐个排除日志查出来的时间和实际发生时间对不上这个抱怨我至少处理过七八次根因分布很分散。来源一采集时间被当成了事件时间。如果应用输出的日志行里没有时间戳采集端只能用它读到的时刻作为时间那么从写入到被读取之间的延迟全部计入误差。日志量大、队列积压的时候这个误差能到几分钟。修法是让应用在每行日志里带上时间戳并且用统一格式。来源二时区。应用用本地时区输出采集端按 UTC 解析或者反过来。表现是所有日志整齐地偏移固定的几个小时很好认。统一原则应用输出带时区偏移的 ISO 格式时间采集端不做任何时区猜测。来源三日志框架的缓冲刷新。有些框架会把日志先攒在内存里攒够一批或者定时器触发才写盘于是文件里的时间戳是产生时间但实际写盘时间晚了很多。这个延迟平时看不出来一出问题就会发现日志的最后一条比实际故障时间早了半分钟很容易误导判断。来源四时钟不同步。多台机器之间的时钟有偏差汇聚到一起排序就乱了。这个要靠基础设施层解决但在排查的时候一定要先排除随便挑两台机器跑一下时间对比差超过一秒就先修时钟再谈日志。6. 别让采集端成为盲区自身指标与灰度上线的节奏采集端最尴尬的地方在于它是用来观测别人的但它自己出问题时往往没人观测。我坚持的做法是采集端上线的同时它自身的监控必须一起上否则你会在某天发现日志少了三天却完全无法回溯原因。6.1 必须盯住的六个指标指标含义异常时的典型含义已采集字节数/行数单位时间读取量突然归零说明文件发现失败突然暴涨说明有异常输出投递成功字节数单位时间发出去的量与读取量持续背离说明队列在堆积队列长度内存中待发数据量持续高位说明远端慢或网络有问题丢弃计数因队列满或过滤丢弃的量非零就必须告警这是真实的日志缺口打开文件数当前持有的句柄接近系统上限时新文件将无法被采集采集端自身资源CPU、内存、IO突增说明配置有问题或有异常日志源这六个里丢弃计数是最重要的一个也是最容易被忽略的。很多团队只监控采集端是否存活进程活着就认为一切正常结果队列一直在丢数据界面上只是日志有点稀疏没人发现。我的要求是把这个指标做成告警只要一分钟内非零就通知因为每一次丢弃都是不可恢复的排查素材损失。队列长度这个指标要结合容量看。如果容量是 512MB队列长期在 300MB 以上说明你的投递速度跟不上产生速度可能是批量参数太小、并发太低也可能是远端一直在限流。这时候盲目加容量只会延迟爆发时间正确做法是查投递环节的耗时分布。6.2 上线节奏从小流量开始把验证做成可重复的采集端这类基础设施组件最忌讳一次性全量铺开。我的标准节奏是三步。第一步单机验证。挑一台非核心业务的机器配好之后观察至少一个完整的日志轮转周期。为什么要等一个轮转周期因为轮转是最容易出问题的时刻前面讲的 inode 复用、压缩包误读、进度错乱全都在这个时间点暴露。只看平时正常运行的两小时什么问题都发现不了。第二步小流量灰度。选一个业务量占比 5% 左右的服务接入重点看三件事日志总量与接入前的估算是否吻合、随机抽取若干条日志核对内容是否完整尤其是多行合并的部分、观察队列长度和丢弃计数是否稳定在零。第三步分批推开每批之间留出观察窗口任何一批出现丢弃计数非零就暂停。验证环节我建议做成脚本而不是人肉抽查。核心逻辑很简单给定一个时间窗口在机器上统计匹配某几个特征字符串的行数再到检索端用同样的条件统计两者比对。这个脚本一旦写好每次扩容、每次改配置都能跑一遍比你拍脑袋相信配置正确可靠得多。我在一个项目里就是靠这个脚本发现了一批机器上多行合并规则写错版本导致堆栈日志只有首行被保留——靠人眼看检索界面几乎不可能注意到这种缺失。最后分享一个我自己的习惯每次调整采集配置我都把改动前后的关键指标截一份存起来和变更说明放在一起。日志系统的问题往往有滞后性今天改的配置可能三天后才以日志变少了的形式表现出来那时候你手里有对比数据定位速度完全不是一个量级。这套东西听起来琐碎但它是让日志真正可用的前提——一套偶尔丢数据、时间还不太准的日志系统用起来比没有更危险因为它会让你在错误的信息上做出判断。 
长河君 · 2026/11/2 17:23:41 · 阅读 1.2k 日志采集Agent核心机制与排错实战：文件发现、多行合并与缓冲队列
深夜两点被电话叫起来查一个偶发超时登录机器tail -f翻到的那份日志里早就没有出问题的那个时间点了——文件被轮转、压缩、清理一气呵成切到容器里执行logs命令只剩最近十分钟的输出三个副本分散在三台机器上逐个登上去 grep 的效率约等于零。这类场景我经历过不止一次也正是从那时候开始我把实时日志管理从出问题再去翻文件改成了日志持续往外流、随时可检索。标题里提到的这款 Agent就是这条链路最前端的那一环它常驻在机器上盯着你指定的文件把新增的行读出来、拼装、打标签、送到远端。这篇东西写给两类人一类是正准备给项目接入日志采集、但被一堆配置项和多行合并规则绕晕的另一类是已经接入了但总感觉日志好像少了点查出来的时间对不上的。我不会停留在装好就能用这个层面而是把采集端内部那几个真正会出问题的机制拆开讲——文件是怎么被发现的、多行是怎么被拼回去的、缓冲队列在压力下会怎么表现——然后给出可以直接抄的配置和一条完整的排错链路。工具的具体名字不重要各家的采集端在原理上大同小异你把这套逻辑吃透换成任何一个实现都能快速上手。1. 采集端在链路里的真实位置它做的不是收集是流处理前端很多人对采集 Agent 的认知停留在把文件内容发走于是配置的时候就填一个路径、填一个目标地址剩下的交给默认值。这种认知在测试环境完全够用一上生产就会暴露问题明明应用打了日志采集端那边却少了几分钟报错堆栈在界面上变成几十条孤立的单行某台机器 CPU 飙高登录一看是采集进程把内存吃满了。这些都不是工具不好用而是你把一个流处理前端当成了文件拷贝工具。1.1 排查现场失效的三个断点先把痛点摆清楚后面的设计才有依据。第一个断点是时间窗口。本地文件是有生命周期的日志框架按大小或按天轮转运维脚本按保留天数清理一个偶发问题从发生到你开始排查中间可能已经过去了几个小时甚至一天。等你登录机器相关文件要么被压缩成归档包要么已经被删掉。第二个断点是位置分散。现在的服务很少有单实例部署一次请求可能落在任意一个副本上靠人肉逐个登录去 grep成本高到不可接受而且你根本不知道该登哪台。第三个断点是上下文缺失。文件里只有一行行文本谁产生的、哪个环境、哪个版本、哪个请求全靠你自己从内容里猜。采集 Agent 解决的正是这三个断点它把事后找文件变成事中持续搬运把分散在各机器变成汇聚到一处把纯文本变成带标签的结构化记录。理解了这一点你就明白为什么它的配置项里有那么多看起来无关紧要的东西——路径匹配、排除规则、标签注入、解析规则每一项都对应上面某个断点。1.2 从应用写盘到你能搜到中间隔着五道关卡我在给团队做分享时习惯画一张链路图这里用文字描述一条日志从产生到可检索至少要穿过五道关卡每一道都可能丢东西关卡环节典型失效表现常见原因1应用写盘日志根本没落地输出被重定向到 stdout、缓冲区未 flush、日志级别过滤2采集端发现文件新文件长时间没被读取inotify 监听数超限、路径通配符写错、目录权限不足3行读取与合并堆栈被拆成几十条多行规则正则不匹配、规则顺序错误4缓冲与投递高峰期日志延迟或丢失队列满后丢弃策略、网络抖动、批量参数不合理5远端入库与检索搜不到或标签错标签冲突、字段类型不匹配、索引延迟把这五道关卡记住后面任何日志不对劲的问题你都可以按顺序往下切而不是面对一个黑盒瞎猜。我见过太多人一上来就怀疑采集端丢数据最后发现是应用把日志打到了 stdout 而采集端配的是文件路径——第一道关卡就断了。2. 文件发现、多行合并、缓冲投递三个真正决定成败的机制采集端的代码量不大但其中三块逻辑的复杂度远超想象。理解了它们的行为边界你配置的时候就知道哪些默认值不能信哪些参数必须自己算。2.1 文件发现靠的不是遍历目录而是事件监听加轮询兜底多数实现会用操作系统的文件系统事件机制来监听目录变更新文件创建、文件被追加、文件被重命名都能拿到通知。听起来很完美但有两个坑。第一单个进程能监听的目录和文件数量是有上限的容器密度高的机器上光日志目录就能塞进去几千个文件加上应用自身的监听很容易触顶。触顶之后的表现非常隐蔽新创建的文件永远不被读取老文件继续正常采集你在界面上看一切正常只是某几个 Pod 的日志凭空消失了。第二事件机制在某些场景下会漏事件比如网络文件系统、某些容器运行时对日志文件的处理方式、文件被快速创建又重命名。所以成熟的实现都会加一层周期性扫描作为兜底每隔一段时间把目录重新扫一遍看看有没有该采但没在采的文件。这个扫描间隔就是配置项里的scan interval之类的东西默认值往往偏保守。我的经验是把扫描间隔压到 10 秒以内同时观察采集进程的文件描述符数量。日志文件多的时候采集端会同时持有大量打开的文件句柄这时候系统级限制就必须调整否则某个时刻它会因为打不开新文件而静默跳过。这个坑我在一个日志目录挂了几千个文件的机器上踩过表面症状是部分日志延迟两三分钟才出现实际原因是句柄耗尽后进入了缓慢的重试循环。2.2 多行合并一个正则写错报错堆栈就全废了这是采集端最容易被低估的功能也是最容易配错的地方。应用输出的异常堆栈天然是多行的2024-06-11 03:22:17.884 ERROR [order-service,trace9f3a] Request failed java.lang.IllegalStateException: connection pool exhausted at com.example.pool.Pool.borrow(Pool.java:88) at com.example.order.OrderService.place(OrderService.java:142) Caused by: java.net.SocketTimeoutException: Read timed out at com.example.net.Client.read(Client.java:65)默认按行切分的采集端会把它拆成六条独立记录每条都被打上同一个时间戳或者更糟只有第一行有时间戳到了检索端你想看完整链路根本不可能。所以必须在采集配置里声明合并规则以什么模式开头的行是新记录的开始不匹配这个模式的行就追加到上一条。规则看起来简单坑在于三点。一是规则的锚定方式。你要匹配的是时间戳加日志级别这种行首特征如果正则没加行首锚定那么堆栈里出现类似格式的行比如某个异常的 message 里恰好带了时间字符串就会误判为新记录的开始把一条完整的堆栈劈成两半。二是状态机的最长等待。如果某条记录的第一行写出去之后后续行迟迟不来应用卡住了采集端需要有超时机制把它强制刷出去否则这条日志会一直挂在内存里直到超时或者文件被轮转。三是应用自身行为的配合。如果应用是把堆栈直接printStackTrace到标准输出而日志框架又在外面包了一层两条输出流的时序可能交错合并在物理上就不可能正确。这种情况要从应用侧改成一次性输出完整异常字符串而不是指望采集端猜。# 多行合并的常见写法示意字段名以实际实现为准 multiline: # 只有匹配这个模式的行才被认定为一条新日志的开始 start_pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} # 合并状态最多保持多久超时强制刷出防止内存里挂死 flush_after: 2s # 单条记录的最大行数防止某条日志无限膨胀 max_lines: 500max_lines这个上限非常必要。我遇到过一种情况某个依赖库在异常时会把一个巨大的对象toString全打出来单条日志几十万行采集端内存直接翻倍然后被系统的内存限制干掉顺便把同一台机器上其他正常的日志也带走了。设了上限之后超出的部分会被强制断开成新记录虽然不完美但至少不会把采集进程整个拖垮。2.3 缓冲队列背压来了之后数据到底去哪了采集端不可能读到一行就发一次网络请求那样开销太大所以它一定有一个内存队列做削峰。链路是读取线程写队列投递线程批量取出来发送。当远端不可用、或者网络变慢的时候队列开始堆积。这时候的行为取决于两个参数队列容量和满了之后的策略。队列容量决定能扛多久的抖动。假设你的日志量是每秒 2MB队列容量 512MB理论上能缓冲四分多钟的断网。这个数字听着够用但要考虑压缩比——传输前通常会压缩队列里存的可能是压缩后的数据实际能扛的时间更长。反过来如果日志里有大量重复内容压缩率很高你反而可能在内存里堆了远超预期条数的记录。满了之后的策略才是关键。常见有三种阻塞读取对应用侧产生反压日志文件写满磁盘最终影响业务、丢弃新数据队列满之后进来的直接扔、丢弃最旧数据把队头弹掉腾位置。这三种没有绝对优劣取决于你对宁可丢也不能卡业务还是宁可卡也不能丢日志的取舍。我的默认选择是在采集端丢弃并计数配合一个丢弃量的监控指标告警。理由很实在日志服务的可用性不应该高于业务本身但你必须知道丢了而且要知道丢了多少。静默丢弃是最坏的方案。3. 部署形态与标签体系决定了三个月后你还能不能查得到工具装在哪、怎么打标签这两件事在接入当天看起来是形式问题实际上它们决定了这套日志体系半年后是资产还是垃圾。3.1 宿主机守护进程、Sidecar、集群级采集的取舍三种主流形态我用一张表对比这里的结论来自几次不同规模项目的实际选择形态适用场景优势代价宿主机常驻进程传统虚机、物理机部署资源占用低与业务生命周期解耦采集配置集中管理需要单独配路径映射容器化环境下路径不直观每 Pod 一个伴生容器容器化早期、需要按业务定制采集规则隔离性好配置随应用走重启不影响他人资源开销成倍增加Pod 数量大时管理成本高集群级采集按节点部署大规模容器集群一台机器一个采集实例成本最优需要在配置里做大量的路径和元数据自动发现我倾向的选择是集群规模小、业务差异大时用伴生容器集群规模上来之后统一切到节点级采集。中间那个过渡期最难熬两套形态并存标签规则不一致检索的时候要在两套体系之间跳。所以如果预判未来一年 Pod 数量会翻几倍一开始就别选伴生方案直接上节点级省下来的迁移成本远超前期多花的配置时间。节点级采集最大的挑战是元数据自动发现。容器里的日志文件在宿主机上是一层软链接指向某个内部路径文件名是一串随机 ID 加上容器 ID。如果你靠硬编码路径去采容器一重启路径就变了。正确的做法是让采集端从容器运行时或者集群的元数据接口拉取信息把容器 ID 映射成服务名、命名空间、实例等标签。这块配置看起来复杂但它是唯一能长期维护的方案。3.2 标签不是给机器看的是给凌晨三点的你看的我在几个项目里见过的最糟糕的标签设计是所有日志一律打上envprod, appbackend然后靠日志内容里的字符串区分服务。结果是每次排查要写复杂的全文检索条件还得祈祷日志格式一致。标签设计的核心原则是任何你在检索时想用来先缩小范围的维度都必须是一个标签。我的最小标签集是这样的service服务名与部署单元一一对应不做任何缩写env环境取值只用固定的几个枚举不要出现prod、production、prd三种写法instance实例标识能用节点名加序号就别用随机 IDversion构建版本号排查是不是这次发布引入的时是刚需log_type日志类别比如app、access、gc、audit方便分索引和分保留策略前四个是基础第五个往往被忽略但价值很高。访问日志、GC 日志、审计日志的数据量级、保留周期、检索频率完全不同混在一起你只能按最大的那个标准来定保留策略成本白白浪费。分类型之后审计日志可以留一年GC 日志留三天各取所需。还有一个细节标签值的基数。千万别把请求 ID、用户 ID 这类高基数信息打成标签那会让索引端直接崩掉而且检索性能急剧下降。这类信息应该放在日志正文或者结构化字段里而不是标签。我见过一个团队把 trace ID 当标签用一天之内索引分片数暴涨最后不得不重建整个索引。4. 一份能直接跑的配置路径、解析、脱敏逐项拆解配置这块我不打算只给一份模板而是逐项说明为什么这么写。你要能改而不是只能抄。4.1 采集路径与排除规则# 采集端主配置字段名以实际实现为准逻辑通用 sources: - name: app-logs # 用通配符覆盖按天轮转的文件 paths: - /var/log/app/*.log - /var/log/app/*.log.1 # 排除规则必须写否则压缩包和临时文件都会被读 exclude: - /var/log/app/*.gz - /var/log/app/*.tmp - /var/log/app/archive/** # 从文件末尾开始读避免首次启动把历史全量灌进去 start_position: end tags: service: order-api env: prod log_type: app multiline: start_pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} flush_after: 2s max_lines: 500几个点值得单独说。start_position这个选项如果设成从头读第一次启动的时候会把目录下所有历史日志一次性发出去几 GB 的数据瞬间灌进来远端可能直接限流本地队列瞬间打满然后开始丢数据——你会以为是采集端有 bug其实是自己的配置在自助式拒绝服务。反过来设成从末尾读意味着首次启动之前的内容全都不要这在大多数场景没问题但如果你接这套东西的动机就是补一下历史日志那就要在维护窗口里单独处理别指望日常配置兼顾。排除规则那一段最容易被漏掉的是压缩包。日志轮转之后通常会被压缩成.gz如果采集路径用了宽泛的通配符采集端会尝试去读压缩文件读出二进制乱码白白消耗带宽和存储空间还会污染检索结果。.tmp同理有些应用会先写临时文件再重命名读半成品没有意义。归档目录更要排除那是给人手动查的不是给采集端读的。name字段看似无关紧要但它常常是排查配置是否生效的第一入口。给每个来源起一个能一眼看懂的独立名字后面看采集端自身的统计指标时你能立刻定位是哪个来源出问题而不是面对一个整体的已采集字节数发懵。4.2 脱敏、采样与资源天花板日志里带敏感信息是常态手机号、身份证号、令牌、连接串随手一打就进去了。指望开发同学每处都记得脱敏不现实所以在采集端做一层兜底是必要的。# 采集端的过滤与脱敏示意 filters: # 正则替换顺序执行先处理最具体的模式 - type: replace pattern: (?i)(password|token|secret)([^\s]) replacement: $1*** - type: replace pattern: \b1[3-9]\d{9}\b replacement: 1********** # 丢弃健康检查的噪音日志这类日志通常占三成以上 - type: exclude pattern: GET /healthz HTTP/1\.1 200健康检查日志的过滤这一条建议每个项目都加上。我做过的统计里某些服务的健康检查请求能占到总请求数的三到五成这些日志除了占空间没有任何排查价值。过滤掉之后存储成本和检索噪音同时下降收益非常直接。资源天花板必须显式设置。采集进程跑在业务机器上它抢走的每一份 CPU 和内存都是业务的损失。要设置的三项是单文件读取的速率上限防止某个超大日志文件吸干 IO、进程内存上限超过就触发自我保护先丢队列而不是被杀、批量投递的条数和字节数。速率上限这条尤其重要我遇到过一次事故某个调试开关忘了关一个服务的日志输出速度暴涨了几十倍采集端全速读取磁盘 IO 被打满业务请求的超时率跟着上去了。后来加了速率限制超出部分只记录丢弃计数反而更稳。5. 丢日志、重复日志、时间错乱三类故障的完整排查链路这一节是我最想写的部分。日志系统的问题里90% 可以归到这三类而每一类的根因分布都很集中。我把排查顺序写出来你可以照着走。5.1 静默丢日志先查 inode 复用再查轮转现象某个时间段的日志在检索端完全找不到前后时间段正常采集端自身没有报错。排查链路是这样的。第一步确认文件本身在不在。去机器上看那个时间段对应的文件是否还存在如果已经被清理那就是保留策略的问题跟采集端无关得回头调轮转和清理的窗口确保清理之前数据已经搬运完毕。第二步如果文件还在用wc -l数一下总行数再去检索端数同一时间范围的行数差值就是丢的量。第三步看采集端的读取进度记录——多数实现会在本地维护一个偏移量文件记录每个文件读到哪了。如果这个偏移量比文件实际大小还大说明它读到了未来的位置。这就是最隐蔽的那个坑文件轮转之后 inode 被复用。日志文件被重命名新文件被创建如果新文件恰好复用了旧的 inode 编号而采集端的进度记录是按 inode 做索引的它就会认为这个文件我已经读到第 N 字节了于是新文件的前 N 字节被直接跳过一声不吭。这种丢失极其难查因为所有指标都正常只有内容凭空少了。规避方式有两个一是让轮转配置使用复制后截断模式而不是重命名模式代价是一瞬间磁盘占用翻倍二是确保采集端在记录进度时同时校验文件的创建时间或者设备号而不只看 inode。第二种是更根本的方案但取决于实现是否支持选型的时候值得专门问一句。第四步如果偏移量正常那就往上追到文件发现环节检查前面说的监听上限和句柄数。这条我建议做成例行检查定期对比应该存在的日志文件数和采集端实际在采的文件数两个数字对不上就是有问题的前兆。5.2 重复投递的三种真实成因重复日志比丢日志温和但它同样是问题会让统计口径全乱。成因基本就三种。第一种是采集端重启后的重发。为了保证至少一次投递多数实现会在确认远端接收成功之后才推进本地进度。如果进程在发送成功但进度未落盘的窗口里被杀掉重启后会从上次的进度重新读这一段就重复了。这个窗口的大小取决于进度落盘的频率落盘太频繁会影响性能太稀疏会放大重复量。我的经验是把它控制在秒级重复量可以接受因为下游可以用唯一 ID 去重。第二种是同一份日志被多个来源采集。比如你既配了/var/log/app/*.log又配了/var/log/app/order.log那么 order 这个文件会被两条规则同时命中每条日志发两遍。这种重复非常好认——重复的两条在时间上几乎完全一致标签却不同。排查方法就是把所有采集路径列出来两两取交集看有没有包含关系。宽泛通配符和精确路径混用几乎是必踩的坑。第三种是日志被写了两遍。应用配置里同时挂了文件输出和标准输出而采集端两边都在采。这种情况重复的两条内容完全一致、标签完全相同只有采集来源不同。解决办法是从应用侧关掉一条输出路径或者在采集端明确只采其中一条。5.3 时间戳错乱四个来源逐个排除日志查出来的时间和实际发生时间对不上这个抱怨我至少处理过七八次根因分布很分散。来源一采集时间被当成了事件时间。如果应用输出的日志行里没有时间戳采集端只能用它读到的时刻作为时间那么从写入到被读取之间的延迟全部计入误差。日志量大、队列积压的时候这个误差能到几分钟。修法是让应用在每行日志里带上时间戳并且用统一格式。来源二时区。应用用本地时区输出采集端按 UTC 解析或者反过来。表现是所有日志整齐地偏移固定的几个小时很好认。统一原则应用输出带时区偏移的 ISO 格式时间采集端不做任何时区猜测。来源三日志框架的缓冲刷新。有些框架会把日志先攒在内存里攒够一批或者定时器触发才写盘于是文件里的时间戳是产生时间但实际写盘时间晚了很多。这个延迟平时看不出来一出问题就会发现日志的最后一条比实际故障时间早了半分钟很容易误导判断。来源四时钟不同步。多台机器之间的时钟有偏差汇聚到一起排序就乱了。这个要靠基础设施层解决但在排查的时候一定要先排除随便挑两台机器跑一下时间对比差超过一秒就先修时钟再谈日志。6. 别让采集端成为盲区自身指标与灰度上线的节奏采集端最尴尬的地方在于它是用来观测别人的但它自己出问题时往往没人观测。我坚持的做法是采集端上线的同时它自身的监控必须一起上否则你会在某天发现日志少了三天却完全无法回溯原因。6.1 必须盯住的六个指标指标含义异常时的典型含义已采集字节数/行数单位时间读取量突然归零说明文件发现失败突然暴涨说明有异常输出投递成功字节数单位时间发出去的量与读取量持续背离说明队列在堆积队列长度内存中待发数据量持续高位说明远端慢或网络有问题丢弃计数因队列满或过滤丢弃的量非零就必须告警这是真实的日志缺口打开文件数当前持有的句柄接近系统上限时新文件将无法被采集采集端自身资源CPU、内存、IO突增说明配置有问题或有异常日志源这六个里丢弃计数是最重要的一个也是最容易被忽略的。很多团队只监控采集端是否存活进程活着就认为一切正常结果队列一直在丢数据界面上只是日志有点稀疏没人发现。我的要求是把这个指标做成告警只要一分钟内非零就通知因为每一次丢弃都是不可恢复的排查素材损失。队列长度这个指标要结合容量看。如果容量是 512MB队列长期在 300MB 以上说明你的投递速度跟不上产生速度可能是批量参数太小、并发太低也可能是远端一直在限流。这时候盲目加容量只会延迟爆发时间正确做法是查投递环节的耗时分布。6.2 上线节奏从小流量开始把验证做成可重复的采集端这类基础设施组件最忌讳一次性全量铺开。我的标准节奏是三步。第一步单机验证。挑一台非核心业务的机器配好之后观察至少一个完整的日志轮转周期。为什么要等一个轮转周期因为轮转是最容易出问题的时刻前面讲的 inode 复用、压缩包误读、进度错乱全都在这个时间点暴露。只看平时正常运行的两小时什么问题都发现不了。第二步小流量灰度。选一个业务量占比 5% 左右的服务接入重点看三件事日志总量与接入前的估算是否吻合、随机抽取若干条日志核对内容是否完整尤其是多行合并的部分、观察队列长度和丢弃计数是否稳定在零。第三步分批推开每批之间留出观察窗口任何一批出现丢弃计数非零就暂停。验证环节我建议做成脚本而不是人肉抽查。核心逻辑很简单给定一个时间窗口在机器上统计匹配某几个特征字符串的行数再到检索端用同样的条件统计两者比对。这个脚本一旦写好每次扩容、每次改配置都能跑一遍比你拍脑袋相信配置正确可靠得多。我在一个项目里就是靠这个脚本发现了一批机器上多行合并规则写错版本导致堆栈日志只有首行被保留——靠人眼看检索界面几乎不可能注意到这种缺失。最后分享一个我自己的习惯每次调整采集配置我都把改动前后的关键指标截一份存起来和变更说明放在一起。日志系统的问题往往有滞后性今天改的配置可能三天后才以日志变少了的形式表现出来那时候你手里有对比数据定位速度完全不是一个量级。这套东西听起来琐碎但它是让日志真正可用的前提——一套偶尔丢数据、时间还不太准的日志系统用起来比没有更危险因为它会让你在错误的信息上做出判断。