← 课程目录 🚀 从零到一
📐 学习维度 阶段7 · 第28章 开源项目源码精读 🚀 从零到一 📚 课程目录 🏠 首页 🛤️ 学习路径

28.10.1 JLog 源码解析:日志采集→传输全链路、异步刷盘与 logback 集成

审校 2026-09-26 · 素材来源:zcode会话《分析项目架构与分布式场景设计》(项目源码分析)
📑 本篇章节导航 (共7节,点击直达)
场景:大促当晚的日志风暴方案对比:四个环节全换掉类比:小区快递柜 vs 上门取件可跑示例:接入 client SDK原理:采集到传输的四道工序踩坑清单面试怎么问

秒级 GB 的日志量,filebeat 读盘再进 Kafka,机器和磁盘先扛不住。京东开源的 JLog 给了另一条路:日志不落盘,在应用进程内直接采集、压缩、UDP 发走。这篇拆前半段链路:怎么拦、怎么攒、怎么发。

场景:大促当晚的日志风暴

App 每秒产生 1G 日志。传统方案是「写本地盘 → filebeat 读 → Kafka → ES」。

问题来了:1G 原始日志走完全链路,磁盘占用膨胀到约 4G。单机处理能力只有约 100M/秒,成本扛不住。

JLog 的取舍很激进:不落盘、UDP 直传、允许丢。同等硬件吞吐提升 10 倍。前提是你接受「日志允许少量丢失」——比如用于链路追踪,不用于审计。

对 5 年 Java 开发来说,这个项目最有价值的不是拿来即用,而是看它怎么在「可靠性、成本、吞吐」三角里做减法。每个环节都问一句:这个保障真的需要吗?不需要就砍掉,换性能。

方案对比:四个环节全换掉

把传统方案和 JLog 逐环节对比,差异一目了然:

环节传统方案JLog 方案
采集filebeat 读盘Filter 拦 HTTP + 自定义 Appender,直接进内存
传输Kafka/TCPUDP 直传,发完即清缓存
存储ES 明文ClickHouse 全程序压缩后入库
查询ES 全文检索仅预定义索引字段

每一环都是用某个能力换另一个能力。采集环节砍掉磁盘 IO,传输环节砍掉重传保证,存储环节砍掉明文换压缩比,查询环节砍掉模糊检索换写入性能。

类比:小区快递柜 vs 上门取件

传统方案像快递柜:先把包裹塞柜子(落盘),快递员再来取(filebeat),中转站再分拣(Kafka)。

JLog 像上门取件:快递员直接在你家门口收走(进程内拦截),装袋压缩(Zstd),电动车上直接送出(UDP),不进任何中转仓。快,但堵车时可能丢一两件。

可跑示例:接入 client SDK


<!-- 业务应用引入 jlog client -->
<dependency>
  <groupId>com.jd.jlog</groupId>
  <artifactId>jlog-client</artifactId>
</dependency>

// 启动时构建 client(Builder 链式收集配置)
TracerClientStarter.builder()
    .appName("order-service")
    .sendMode("udp")            // 小包 UDP,大包自动转 HTTP
    .build()
    .start();

<!-- logback.xml:把自定义 Appender 挂上,日志自动关联 tracerId -->
<appender name="TRACER" class="com.jd.jlog.client.logback.TracerLogbackAppender">
</appender>
<root level="info">
  <appender-ref ref="TRACER"/>
</root>

启动后,HTTP 请求的出入参和沿途日志都会被 tracerId 串起来,发往 {{WORKER_HOST}}:9999。

想验证链路,先把 worker 起起来,worker 会把 ip:9999 注册到配置中心的 workers 这个 key。client 每 30 秒拉一次这个列表,拿到地址后开始发数据。用 {{DEMO_USER}} 的账号下一单,去 Dashboard 按 tracerId 搜,就能看到这次请求在各个服务里的完整轨迹。

原理:采集到传输的四道工序

第一道,拦截。HttpFilter 实现 javax.servlet.Filter,拦下每个请求。它做三件事:

1. IdWorker 生成 tracerId,放进 TransmittableThreadLocal(可跨线程池传递的 ThreadLocal,普通 ThreadLocal 在线程池里会丢上下文)

2. 用 RequestWrapper/ResponseWrapper 装饰 request/response——body 流默认只能读一次,装饰后缓存字节才能重复读取

3. 按 ITracerPercent 采样策略决定记不记(默认 DefaultTracerPercentImpl 返回 100,即全采;大促时可注入动态实现降到 30%)

第二道,关联日志。TracerLogbackAppender extends AppenderBase、TracerLog4J2Appender 用 @Plugin 注解挂进日志框架。本质是观察者模式:日志框架是被观察者,Appender 是观察者。每条日志写出来时,从 TracerHolder 取出当前 tracerId 一起打包。

这个设计让接入零侵入:业务代码一行不改,只动 logback.xml 加一个 appender 声明,所有既有日志就自动带上了 tracerId。比起满代码埋点,这是成本最低的链路串联方式。

第三道,异步攒批。两条 LinkedBlockingQueue(50000) 分别存出入参和日志。AsyncWorker.drain() 实现有界批量加超时刷盘:攒满 batchSize 或超时 interval 秒就 flush 一次。这套写法借鉴了 log4j2 的批量消费惯用法。

为什么必须异步?如果同步发日志,一次网络抖动就把业务线程卡住,日志组件反过来拖垮主业务,本末倒置。内存队列把「产生日志」和「发送日志」彻底解耦:业务线程只做一次入队,纳秒级返回;发送线程慢慢攒、慢慢压、慢慢发。注意用的是 offer 不是 put——队列满了直接丢弃。这是有意的背压策略:保业务系统,牺牲日志。

第四道,压缩发送。Netty 的编码器 UdpClient.MyUdpEncoder 串成一条责任链:


Protostuff 序列化 → Zstd 压缩 → 大小判断(>60K 转 HTTP) → 选 worker 地址 → UDP 发包

选地址靠 WorkerInfoHolder.chooseWorker() 轮询。worker 列表每 30 秒从配置中心拉一次刷新;列表为空时回退到 127.0.0.1:9999。

发完即清缓存,不占堆外内存,这是 UDP 方案吞吐高的核心原因。

再看几个源码细节。TracerClientStarter.Builder 是标准建造者模式,链式收集 appName、mdc、tagConfig、sendMode 后一次构建,避免多参数构造器的可读性灾难。

Context 是进程级静态上下文,存 APP_NAME、Channel、MDC 这类全局信息。和 TracerHolder 的线程级上下文分工明确:一个进程一份,一个线程一份。

配置中心的选择用 SPI 做到可插拔:ConfiguratorFactory 用 JDK 原生 ServiceLoader 加载 ConfiguratorProvider,引 config-etcd 就用 etcd,引 config-zk 就用 zk,nacos、apollo 同理。业务代码零改动。

踩坑清单

面试怎么问

「JLog 为什么敢用 UDP 传日志?」——答:日志场景允许少量丢失,UDP 免去 TCP 握手重传的开销,发完即清缓存不堆内存,配合 Zstd 全链路压缩,同等硬件吞吐提升 10 倍。

「tracerId 怎么跨线程池传递?」——答:用 TransmittableThreadLocal 而非普通 ThreadLocal,TTL 在任务提交时捕获、执行时恢复上下文,线程池复用线程也不会丢。

「日志框架怎么被 hook 进来的?」——答:自定义 Appender 继承 logback 的 AppenderBase、log4j2 走 @Plugin 工厂,本质是日志框架提供的观察者扩展点,日志写出时被回调并关联 tracerId。