双十一刚过完Spring Boot 3.4 就悄悄发了正式版。版本号从 3.3 跳到 3.4release notes 里塞了一大堆依赖升级但真正让我觉得这版值得认真对待的是结构化日志Structured Logging终于被官方扶正了。做过几年 Java 后端的人应该都有这种体验线上出问题第一反应是登服务器 grep 日志结果日志文件里全是时间格式各异、多行堆栈满天飞的纯文本正则写到怀疑人生几千行里找不到一条完整请求的上下文。这篇文章不打算把 3.4 的所有特性都过一遍我重点聊聊结构化日志这个新能力它解决什么问题、底层怎么实现、生产环境怎么接 ELK以及我实际升级和压测时踩到的一些细节。1. 为什么日志可观测性会卡在格式这一关1.1 文本日志的天花板传统 Logback 的默认输出长这样2024-11-22 10:15:30.123 [http-nio-8080-exec-1] INFO com.example.OrderService - 订单创建成功订单号202411220001这种格式人眼看起来没问题甚至习惯了之后还挺亲切。但它有两个致命问题第一机器解析困难。日志平台要识别时间、级别、日志器名全靠正则模板。你的业务消息里只要多一个引号、方括号、换行符正则就断给你看。第二多行内容有去无回。一个异常堆栈动辄十几行在纯文本采集方案里经常被切得七零八落日志平台里按异常类型聚合统计基本做不到。我自己线上排障最痛苦的场景就是同时查十几台机器的日志先 grep 订单号再顺着线程号找上下文最后对着时间戳手动拼完整链路。说实话做了这么多年后端看到纯文本日志从一堆服务里捞一条请求依然像在草丛里找一根针。1.2 结构化日志不是打印 JSON这么简单很多人以为结构化日志就是把logger.info(xxx)改成拼一段 JSON 字符串然后输出到文件。大错特错。结构化日志的核心是语义化、类型化、自描述。普通文本日志是一条给人看的字符串结构化日志是一条给机器读的事件。区别在哪以一条典型的 JSON 日志为例{timestamp:2024-11-22T10:15:30.123Z,log.level:INFO,message:订单创建成功,log.logger:com.example.OrderService,thread.name:http-nio-8080-exec-1,trace.id:abc123}时间就是timestamp字段级别就是log.level链路 ID 就是trace.id。日志平台拿到这种数据不需要正则直接按字段建索引、做聚合、画图表。你甚至可以把多个服务的日志按trace.id拼成一条完整的分布式调用链。这才是可观测性三个字的底气。1.3 Spring Boot 3.4 给出的官方答案过去想在 Spring Boot 里输出 JSON 日志主流方案是引入logstash-logback-encoder自己配置 LogstashEncoder再手动挑选字段处理 MDC 映射。这套方案本身没问题但它有个绕不开的痛点字段名、层级风格、布点方式完全靠团队自觉。你公司里三个服务可能写出三种 JSON 格式。Spring Boot 3.4 直接把结构化日志做进了框架里。它不用你额外引 encoder 依赖只需要在配置里声明想要的格式logging: structured: format: console: ecs一行配置输出立刻变成标准 JSON。而且官方给了ecs和logstash两种成熟格式团队之间终于不用再为了字段命名打架了。2. 官方结构化日志的底层实现与配置语义2.1 基于 Logback但是没有动你现有的架构Spring Boot 3.4 默认日志系统依然是 Logback。这次官方在 starter 里内置了 Logback 的 JSON 支持核心思路是往 Logback 里注册一个专门的 Formatter替换掉原来的PatternLayout。这里有一个让我比较安心的设计它没有另起炉灶而是复用了 Logback 的整个 appender 体系。你原本配置的RollingFileAppender、AsyncAppender、各种 Filter全部照常工作。变的只是日志事件最终被格式化为什么样子采集、滚动、异步写磁盘这些机制一概不动。老项目迁移的侵入性是非常小的。2.2 两种内置格式ecs 与 logstash3.4 内置了两种 JSON 格式。我建议把它当作一个选择题而不是开放题格式适用平台/场景字段风格ecsElasticsearch、Loki 等标准生态嵌套字段如log.level、log.logger、trace.id贴合 Elastic Common Schemalogstash传统 ELK、已有 Logstash pipeline扁平字段如level、logger_name、thread_name兼容老 logstash-logback-encoder 用户我用一个简单比喻理解这两者logstash是老式别墅平层板正老住户习惯就好ecs是精装公寓按现代物业标准统一管理新小区基本都按这个移交。如果你的日志栈从零开始我推荐ecs因为字段规范、可扩展性强如果线上已经跑着老 Logstash 管道为了不折腾解析端可以先选logstash过渡。2.3 配置项的语义与优先级细节logging.structured.format.console和logging.structured.format.file两个配置项分别控制控制台和文件输出。它俩可以不一样logging: structured: format: console: logstash file: ecs比如本地开发把 console 配成 JSON方便肉眼核对字段生产环境 file 配成ecs落盘给采集器。也可以 console 完全不配只在 file 上开 JSON——这样本地控制台还是原来的彩色纯文本生产日志照样结构化。这里有一个非常重要的细节一旦某个输出端开启了 structured format这个输出端上的logging.pattern.console或logging.pattern.file就会被忽略。两者是互斥关系不是叠加关系。我一开始没注意生产配置里同时留了两套结果自定义的高亮 pattern 完全不生效控制台直接刷出一片 JSON 文本。另外3.4 还预留了自定义扩展点可以通过注册LogbackStructuredLoggingJsonProvider类型的 bean往 JSON 里追加自己的字段。这个扩展点很实用后面讲业务埋点时我会具体展开。理论上限讲完下面进入落地环节。3. 落地实操把 Spring Boot 3.4 服务接进 ELK3.1 项目准备与依赖说明先说结论你不需要往pom.xml里加任何额外的 JSON 日志依赖。只要项目用的是 3.4.x 版本spring-boot-starter-logging里已经包含了官方结构化日志支持。最小准备包括Spring Boot 3.4.x 项目使用spring-boot-starter-web或任何 starter日志依赖是公共的一个application.yml一个能收 JSON 的采集端比如 Filebeat、Logstash 或 Loki如果是从 Spring Initializr 新建项目版本选 3.4.x 后都不用额外操作配置文件一改就生效这个对新手非常友好。IDE 方面社区版 IDEA 跑 Spring Boot 3.4 没有任何障碍Maven 或 Gradle 环境配好即可。3.2 最小配置与输出效果一个最简配置spring: application: name: order-service logging: structured: format: file: ecs启动后日志文件里的一条记录会变成类似这样{timestamp:2024-11-22T10:15:30.123Z,log.level:INFO,message:Started OrderService in 1.234 seconds,log.logger:com.example.OrderService,thread.name:main}注意message字段里就是原始日志文本没有多余的换行。即便是异常堆栈也会被当作stack_trace字段放进同一行 JSON。这一条对于采集端来说价值极大一个 JSON 对象就是一个完整的日志事件不再有跨行拼接问题。3.3 配套 Filebeat 采集配置如果 ELK 栈的采集端用 Filebeat配置文件需要注意一点用ndjson解析器直接解析每行 JSON而不是用普通文本解析后自己拼。filebeat.inputs: - type: filestream paths: - /var/log/apps/order-service/*.log parsers: - ndjson: keys_under_root: true add_error_key: true overwrite_keys: true message_key: message几个参数解释一下keys_under_root把 JSON 里的字段直接提升到事件根节点保存到 ES 后字段路径更短。add_error_key解析失败时把原始内容放进 error 字段方便排查。overwrite_keys允许解析出来的字段覆盖 Filebeat 自带的默认字段。message_key指定哪个字段是日志正文对检索友好。最重要的坑是不要打开 multiline 配置。很多从纯文本时代迁移过来的同学习惯靠multiline.pattern拼堆栈结果 JSON 日志每行都是一条完整记录再一拼就把语句切坏了。3.4 跨语言栈的场景Java 与 Python 服务统一格式顺带回应一下最近总被问到的Spring Boot 3 和 Python FastAPI对比问题。实际生产里多语言并存非常常见。以前 Java 走 Logback 纯文本Python FastAPI 走自己的 logging 格式采集端就得维护两套解析规则。现在 Java 端统一输出 ECS JSONPython 端也可以用类似python-json-logger的库或自己写一个 middleware输出同样字段命名的时间、级别、消息和 traceId。这样 Filebeat 配置一套到底ES 索引模板也只需要一套。语言可以百花齐放但日志规范必须收敛成一种。4. 让 JSON 日志真正服务于排查traceId 与业务字段4.1 traceId 如何自动进入 JSON结构化日志单独用价值有限真正发挥威力的是和链路追踪结合。Spring Boot 3.4 对 Micrometer Tracing 的自动装配更成熟了你只要引入链路桥接依赖dependency groupIdio.micrometer/groupId artifactIdmicrometer-tracing-bridge-otel/artifactId /dependency启动应用后结构化日志的 JSON 里就会自动出现 trace 相关字段。Logstash 风格下是trace_id/span_idECS 风格下是trace.id/span.id不需要你手动改任何 pattern。这一点非常省心因为跨服务调用时只要 HTTP 头里把 traceId 传下去下游服务打印的日志也能归属到同一条链路。如果暂时不打算接入真正的 APM collector只是想让日志带上链路 ID也完全可行。配一下采样率即可management: tracing: sampling: probability: 1.0生产环境如果日志量巨大可以把这个值调低到 0.1 甚至 0.01代价是部分请求的日志没有 traceId换取写入成本的下降。4.2 业务字段如何优雅地塞进 JSON最简单的做法当然是 MDCMDC.put(userId, 9527); log.info(订单创建成功); MDC.remove(userId);但这样写多了之后业务代码里全是 MDC 的 put/remove很脏。更工程化的做法是注册一个自定义的LogbackStructuredLoggingJsonProvider把当前用户、业务模块这种公共字段统一写入 JSON。大致思路实现一个类继承官方 provider从上下文里获取当前登录用户比如从SecurityContextHolder或自研上下文组件读取然后调用 JSON generator 写入字段。业务代码只需要在入口处设置一次上下文后续所有日志都会自动携带user.id字段。这个思路跟拦截器配合更顺既保持了日志结构的统一又不用到处埋点。4.3 一个真实排查案例日志没有 traceId有一回同事反馈日志平台里 JSON 记录就没有trace_id。我们的排查过程比较典型也值得记录一下第一轮检查依赖。项目里只有spring-boot-starter-web没有 micrometer-tracing 的 bridge。这是最常见的低级原因——没有引入依赖官方想自动装配也无从谈起。补上依赖后重新部署。第二轮看采样率。依赖有了但 trace_id 仍然时有时无。查配置发现management.tracing.sampling.probability用的是默认值只有 0.1 的采样率十有八九日志里带 traceId。调到 1.0 后稳定复现。第三轮查采集端。应用端日志里确实有trace.id了但 Elasticsearch 里还是没有对应字段。最后定位到 Filebeat 旧版本用的还是普通文本解析根本没有按 JSON 展开字段。更新配置后链路字段才算完整走通。这个案例说明一个道理traceId 没出现在日志里先查应用依赖再查采样率最后查采集解析链路。按这个顺序基本十分钟内能定位。5. 升级到 3.4 的检查清单与实测心得5.1 结构化日志到底带来多少性能开销这是我被问得最多的问题。JSON 序列化比字符串拼接慢这是物理事实关键是慢多少。我做了一个简单压测单台 4C8G 的机器跑一个 Spring Boot 3.4 订单服务接口吞吐约 2000 QPSINFO 级别每个请求大约产生 5 条日志。开启 file 端 ECS JSON 输出后吞吐下降约 6%P99 延迟增加 10ms 左右。这个数字在大部分业务场景里完全可接受。但如果你的服务日志量巨大每秒几百条以上我建议用AsyncAppender把文件写盘异步化避免日志 IO 卡住业务线程。推荐配置logging: structured: format: file: ecs同时保持 console 不开启 JSON本地开发时控制台维持纯文本可读性。生产环境如果把 console 也设成 JSON调试起来会非常痛苦滚动日志文件你是不会直接看的控制台才是真正的人机交互界面。5.2 与自定义 logback-spring.xml 的兼容性问题如果你项目里存在自定义的logback-spring.xml并且里面自己定义了 PatternLayout开启 structured format 后该输出端的 pattern 会被结构化 formatter 忽略。我踩过的坑是console 端留了高亮 pattern加format: ecs之后控制台直接刷满 JSON看着相当崩溃。解决方式有两种一是 console 不开启结构化只对 file 开启二是如果自定义 appender 必须保留不要把官方 JSON formatter 和自定义 pattern 混在同一个 appender 上拆成两个输出端各管各的。另外要注意3.4 的 Logback 版本有升级如果你自定义了比较老的Layout子类建议升级前先编译检查一下方法签名有没有废弃。5.3 升级前后的快速检查清单根据我这段时间的实践从 3.3 升级到 3.4可以按这个清单过一遍Spring Framework 6.2 的兼容性。项目里如果强依赖某些已废弃的WebMvcConfigurer方法提前编译一次IDE 会直接标红。检查所有logging.pattern.*配置。开了结构化格式之后这些 pattern 在对应输出端会失效。检查自定义日志组件。如果项目里引入了旧版logstash-logback-encoder且你同时开了官方结构化日志两套 JSON 机制可能重复套娃字段会出现嵌套。建议二选一长期保留官方方案即可。Spring Boot Admin 如果还在用日志查看面板显示的是 JSON 文本可读性会下去一点但功能不受影响实在介意可以只在 file 端开启Admin 走logfileendpoint 时看到的还是纯文本。5.4 我的升级路线建议新项目没有历史包袱直接上 3.4 file 端开ecs一步到位。存量项目我建议分两步走先单独拉分支升级依赖版本跑通测试再把文件输出切到 JSON灰度观察日志平台解析是否正常。切忌在同一个版本里既升级框架又改日志格式——出了问题你根本不知道是框架变更导致的还是日志格式导致的。最后分享一个小技巧想快速验证 3.4 结构化日志不用急着接 ELK。临时把 console 的格式设为logstash启动项目后直接在控制台核对输出字段。字段没问题了再切到生产环境用的ecs并接采集端。这个切换成本就是一行配置的事。这也是我更喜欢 3.4 官方方案而不是自己维护 logstash encoder 的直接原因——集成成本低到你可以随时在两个格式之间来回切换而不用改任何 Java 代码。