★ FEATURED ARTICLE Spring Boot 3.4 正式发布的时候最让我眼前一亮的不是又升级了什么自动配置也不是哪一堆依赖版本号做了同步调整而是默认日志体系里那一大块面向结构化日志的能力调整。身边不少同事看到发布公告后第一反应是“哦又有新版本了”但很少有人真正意识到从 Spring Boot 3.4 开始日志这件事的玩法已经变了。说白了以前我们写日志是给人看的一行一行的文本缩进、颜色、时间戳怎么顺眼怎么来。但从 3.4 开始Spring Boot 把“机器可读”摆到了和“人可读”同等重要的位置官方文档里直接给出了基于 Logback 的 JSON 输出支持并且把结构化日志相关的配置入口收拾得清清楚楚。这件事对于搞微服务、搞容器化部署、搞日志采集分析的人来说意义非常大。如果你正在负责一个多服务系统每天靠 grep 日志排查问题已经排到想吐或者你刚把应用从虚拟机搬到 Kubernetes发现采集到的日志全是一行行挤在一起的文本块那这篇内容值得看完。我会从 Spring Boot 3.4 的结构化日志特性出发讲清楚它解决了什么问题、怎么快速落地、以及我在实际切换过程中踩过的坑。这篇内容不是把官方文档翻译一遍而是按我自己在项目中迁移的真实路径来写的。1. 为什么 Spring Boot 3.4 把结构化日志推到台前1.1 从一行文本到一个事件先聊一个基础的认知转变。传统日志长这样2025-01-12T10:33:22.12308:00 INFO 12345 --- [http-nio-8080-exec-1] com.example.OrderService : create order success, orderId12345这行日志里信息其实挺全的时间、级别、线程、类名、消息都有。但问题是这行日志的“信息”是写给眼睛看的不是写给程序看的。当你把这行日志交给采集器比如 Filebeat、Fluentd 或者直接打到 ClickHouse、Elasticsearch 里程序需要靠正则表达式去拆字段。今天你拆得挺好明天有人在日志消息里多加了一个空格、换行、引号正则就废了字段对不齐查询结果全是坑。而结构化日志的意思是把一条日志当成一个包含多个字段的 JSON 对象来输出{ timestamp: 2025-01-12T10:33:22.12308:00, level: INFO, logger: com.example.OrderService, thread: http-nio-8080-exec-1, message: create order success, orderId: 12345 }程序拿到这个对象以后不需要猜不需要拆直接按 key 取值。你想统计某个接口的 P99 耗时直接对 field 做聚合你想查某个用户在某段时间内的所有操作直接按 userId field 过滤。这个体验上的差距用一句话概括就是文本日志是给 grep 用的结构化日志是给查询和分析用的。1.2 这次不是“JSON 日志”那么简单可能你会说JSON 日志我早就会了自己写个 Logback encoder 不就行了确实以前我们也能做但问题在于没有规范每个团队自己定义字段名有的叫timestamp有的叫timestamp有的叫time有的把 traceId 放logContext里有的放Trace里。到了统一采集端还得为每个服务的日志格式各写一套解析模板维护成本很高。Spring Boot 3.4 做的事情是把结构化日志从“第三方技巧”提到了“框架内置能力”的高度。官方在spring-boot模块里直接支持了 Logback 的 JSON 格式化配置你可以通过logging.structured.logback.customizer这类配置项去启用和定制。也就是说框架帮你把“输出合法 JSON 且符合一定字段规范”这件事收敛到了统一入口而不是让你去网上找一段来路不明、可能还跟你的 Logback 版本不兼容的 encoder 配置。此外3.4 版本对日志分组Log Groups也做了强化你可以把一组 logger 打包成一个分组统一调级别。这个看似不起眼但在排查问题时非常顺手比如把所有 SQL 日志org.hibernate.SQL和com.example.mapper放进同一个分组一条配置就能全部打开 DEBUG不用一个个 logger 写过去。从官方设计意图来看3.4 是希望应用日志从一开始就面向“机器消费”来设计。你写日志的时候心里想的不再是“同事能不能看懂”而是“下游系统能不能直接消费”。这个理念变化才是这次发布里最值得关注的点。2. 结构化日志的落地方式选型与取舍2.1 三种实现路径对比我在项目里见过三种做结构化日志的方式各有各的适用场景。第一种是应用内输出 JSON 日志也就是我们今天聊的方案适合新项目或对日志控制力要求高的场景。第二种是在采集端做解析应用依然输出文本由 Logstash 或 Fluentd 负责把文本转成 JSON适合不打算改应用代码的老系统。第三种是直接用云厂商的日志服务 SDK 上报适合深度绑定某朵云、不太关心本地日志文件的场景。三种方式并不是非此即彼很多项目是混合用的。但从可控性和可移植性来看我比较推荐第一种。原因很简单应用自己输出的结构只有应用自己最清楚。你在代码里如果想给日志加一个businessType字段直接在输出层就加上采集端和存储端完全不用动这种扩展成本是最低的。如果选择在采集端解析每增加一个字段都要同步修改采集端的解析规则。而且一旦应用日志里有异常堆栈堆栈是多行的文本日志里表现得非常不规整采集端的解析配置会迅速变得复杂而脆弱。我们有一个老系统试过用 Grok 表达式去匹配一套祖传日志调试正则就花了两个下午最后还是放弃改成改造应用输出。这个教训我印象很深。下面是三种方式的快速对比方案改造位置优点缺点适合场景应用输出 JSON应用内 Logback/Log4j2 配置字段完全可控、扩展方便需改应用配置并回归验证新项目、重构项目采集端解析Filebeat/Logstash应用不用改解析规则脆弱、字段扩展麻烦老系统过渡期云 SDK 直报业务代码接入快、多端打通绑定平台、本地排障不便强云绑定项目2.2 为什么官方优先推 Logback 方案Spring Boot 默认日志实现一直是 Logback所以官方在 3.4 里优先把结构化日志能力放到 Logback 上是很自然的选择。很多团队用的是 Log4j2也能用但你需要自己引入适配层并且注意版本兼容性。如果你没有历史包袱我建议就跟着默认走用 Logback。这里要解释一个容易踩坑的点Spring Boot 3.4 的logging.structured配置并不是直接让你提供一个 JSON encoder 的 class而是通过内置的LogbackJsonEncoder等组件来完成字段组装。从效果上看它输出一个扁平的 JSON 对象level、logger、thread 这些基础字段都在第一层MDC 里你放的东西也会出现在 JSON 里。这意味着你在代码里往 MDC 里放traceId、userId这部分内容会自动带上不需要为每个字段单独写mdcKey配置。从配置模式来看官方提供的是“基础字段默认、额外字段用 MDC 补充”的路线。你在业务代码里想加字段不用动配置文件只要往 MDC 里放即可MDC.put(orderId, 12345); MDC.put(userId, 98765); log.info(create order success); MDC.remove(orderId); MDC.remove(userId);然后你拿到的 JSON 日志里会自动多出orderId和userId两个字段。这一点是真真切切为了方便而设计的不用再走“自定义 Logback Layout”那条老路。3. 实操从文本日志平滑切换到结构化日志3.1 基线配置先让 JSON 输出跑起来直接说怎么切。如果你用的是 Spring Boot 3.4 及以上版本并且引入了spring-boot-starter-logging配置文件里这样写就能让应用输出 JSON 格式日志logging.structured.format.logbackecsecs是 Elastic Common Schema 的缩写是当前比较通用的一种日志字段规范。设置好以后你本地的控制台日志就会变成 JSON 形式。注意这里不仅是文件日志控制台日志也会变成 JSON开发环境下可能会觉得不太习惯后文我会专门讲兼容开发体验的配置。除了ecs之外还可以配置成logstash它采用的是 Logstash 风格的字段命名比如timestamplogging.structured.format.logbacklogstash两个选哪个我的建议是如果你们日志链路后端是 Elasticsearch 生态且字段统一规范还没定优先考虑ecs因为它规定了一套相对完整的命名空间便于后续做索引映射。如果你们已经有自己的一套timestamp习惯或者正在用 Logstash 中间件选logstash风格更顺手。先选一个跑通后续再微调字段名也不难。3.2 关键参数解释traceId、spanId、异常堆栈、MDC结构化日志的价值一半体现在链路追踪字段上。如果你的项目已经接了 OpenTelemetry 或者类似 SDKtraceId、spanId 会被自动塞到日志上下文里。启用 JSON 输出后你会发现日志里不再需要靠正则去抠一串十六进制字符串了直接就是独立的字段。这也是我特别推荐在链路追踪项目里顺手把结构化日志开起来的原因——你排查问题时点开一条 trace再点开对应的日志两边直接对上不需要人工比对字符串。异常堆栈在文本日志里是一大坨多行文本在 JSON 日志里会变成一个数组或字符串。比如在 ECS 格式下异常信息会作为error相关字段出现。你要注意堆栈内容里可能包含换行符和引号在 JSON 序列化时会被转义所以在看采集平台上的原始日志时你会发现堆栈变成了一行很长的字符串这是正常的不是格式错了。MDC 字段的传递路径也要说清楚。在 Logback 里MDC 是线程级别的 Map你在业务代码里放的 Key只要 JSON Layout 配置了显式或者隐式输出 MDC就会出现在日志字段中。Spring Boot 3.4 的默认策略是会把 MDC 里的内容放到 JSON 里但不同格式 schema 下的字段名有差异。想稳妥起见可以自己加一组mdc字段映射配置确保团队字段命名一致。3.3 兼容性配置让开发环境保持可读这是我自己最在意的一部分。JSON 日志上了生产环境确实香但如果本地开发的时候控制台也是一整行挤在一起的 JSON那调试体验会直线下降。看到一个INFO级别的日志你还得在脑子里做一次 JSON 反序列化才能读懂非常烦。Spring Boot 3.4 里可以通过 profile 来区分格式。比如生产环境用 JSON本地开发用传统文本# application-local.properties logging.structured.format.logbackdisable这里需要确认一下具体配置项名。如果你的版本里不支持disable也可以直接用传统方式覆盖回去。我记得在实际配置过程中我是在application-prod.properties里开启logging.structured.format.logbackecs而在默认配置文件里不设置这样本地启动时就是原来的文本日志部署到生产时自动切到 JSON 输出。这个做法简单粗暴效果非常好。如果你有统一的日志采集需求比如本地开发也希望让日志被 Loki 采集那可以把本地也开成 JSON但建议配合一个“人类可读”的辅助输出比如只打印级别、logger 和 message不要带上完整堆栈的另一种格式。但从实践来看大多数团队最终会选择“本地文本、生产 JSON”的策略。4. 生产环境踩坑实录结构化日志带来的新麻烦4.1 日志内容中的“隐形炸弹”切到 JSON 日志后第一个坑是日志消息本身包含特殊字符。比如业务日志里会输出 URLURL 里经常有和?再比如日志里会输出请求体请求体里又有 JSON 字符串——双引号、反斜杠全都有。如果你在代码里直接log.info(request body: {}, body)body 里的内容被输出到 JSON 字段后虽然会被转义但转义后的日志极难阅读而且如果你的 message 字段被索引搜索一个完整 URL 字符串会变得很考验查询语法。最麻烦的是如果业务日志里被人为拼接了一段带换行符的文本在文件里看时整个 JSON 结构会变得“支离破碎”。当然 Logback 的 JSON encoder 会正确处理字符串转义日志文件不是一个损坏的 JSON但你在 console 直接 tail 日志时肉眼很容易被一大段转义字符晃花眼。我后来给自己定了一条规矩日志消息里不能放大的业务对象尤其是带复杂嵌套结构的对象。需要输出对象时要么只输出关键字段要么把对象按字段拆分后放进 MDC。这样一条日志可能从“一大坨描述性文本”变成“一条结构化记录”查询体验完全不同。4.2 异步日志与线程池的 MDC 陷阱切换 JSON 日志后链路追踪的需求往往会被放大。很多人会在日志打印那一步把 traceId 放进 MDC但如果你的代码用了异步线程池子线程是拿不到父线程 MDC 内容的。日志 JSON 里 traceId 就会凭空消失。这问题在文本日志时代也存在只是没有 JSON 那么明显因为文本日志里即使缺 traceId你还能拿点别的线索。在结构化日志里字段缺失就是缺失分析时直接少了一个关键维度。解决思路有两个。一个是直接在代码里封装线程池提交任务时把父线程的 MDC Context 复制到子线程。ThreadPoolTaskExecutor可以通过TaskDecorator实现这个逻辑。另一种是如果你的链路追踪 SDK 已经提供了跨线程传播能力比如 OpenTelemetry 的 Context Propagation 本身是自带异步传播机制的那么你在日志阶段不应该重新从 MDC 去拿而是要确保日志输出层的 instruments 能从上下文里取出 traceId。从实际效果看后者更系统前者更直觉两条路都值得走。现场排查时如果发现部分日志有 traceId部分没有优先怀疑异步代码。可以先找一次有父链路但子日志断掉的操作看看对应线程名是不是pool-*-thread-*基本就能确定是线程池没有继承上下文的问题。4.3 过滤器和掩码敏感字段漏了没有结构化日志把所有字段都铺平了以后敏感信息也会跟着变得特别好检索。文本日志里你要找一个手机号还得靠正则去翻。JSON 日志里如果业务代码把整对象塞进日志了手机号、身份证、银行卡号可能就静静躺在某个字段里等着被采集走。这里必须做一道过滤。我从实际经历来说结构化日志上线前必须检查每个可能输出用户数据的日志点。最简单的规避方式是日志模板里不出现user、idCard、phone这种 key必要输出时用脱敏工具把中间四位打码之后再放进去。另外还可以在 Logback 配置里加一个自定义 Filter针对包含特定字段的日志直接丢弃或者替换。这一步很容易被忽略但一旦日志链路被别人接了数据分析平台出了事就不是技术问题了。5. 日志字段规范用一套 schema 统一所有服务5.1 最小字段集设计每多一个服务如果没有共同的日志规范最后采集端看到的日志字段维度能五花八门到让你无从下手。Spring Boot 3.4 给了你一个统一入口但统一的是格式框架不是业务字段。所以团队里最好有一个最小的字段集约定。我比较推荐的一套基础字段集是这样的字段含义示例必填timestamp日志产生时间2025-01-12T10:33:22.123Z是level日志级别INFO是logger记录器名称com.example.OrderService是thread线程名http-nio-8080-exec-1是message日志正文create order success是traceId链路追踪号abc123...建议spanId当前 Span IDdef456...建议service.name服务名order-service是businessType业务域trade可选userId用户标识98765可选orderId单据标识12345可选可以看到前七个字段是通用的后面三个是业务字段。有了这组字段你在日志平台里写查询的时候不需要去问某个服务对应的“订单号字段到底叫 orderId 还是 order_no”也不用纠结时间字段叫time还是timestamp。5.2 跨团队协作时日志字段最容易吵起来的地方字段规范这件事写出来容易落实难。最常见的问题是各团队对“同一概念”命名不一致。用户 ID 有的叫userId有的叫uid有的叫accountId一旦上了结构化日志平台这种差异带来的检索麻烦是几何级数上升的。你查一个用户的问题明明那个用户有日志但因为字段名对不上你搜不到。另一个容易忽略的细节是时间格式。JSON 日志里时间字段常见的坑是有的服务输出毫秒时间戳有的输出带时区的 ISO 字符串在排序和范围查询时会出现混乱。Spring Boot 3.4 的 ECS 格式默认用 ISO 8601这个在跨时区场景下非常友好建议如果你们自己定义 schema也用它。我见过最值得夸的一个团队做法是把字段规范写成一个 JSON Schema 文件放到仓库的一个公共目录里各服务引入之后通过单元测试校验自己输出的样例日志字段缺失或类型不对直接测试失败。这个办法很土但效果出奇地好比开会宣贯十遍都管用。6. 迁移评估现有项目要不要升 3.46.1 升级路径与兼容性清单Spring Boot 3.4 并不是一个大版本跳级但它仍然有不少兼容性变化。如果你从 3.2 或 3.3 升级需要关注的点主要有这几个方面。首先是依赖版本基线。Spring Boot 3.4 对应的 Spring Framework 6.2一些第三方 starter 如果还停留在旧版 Jakarta EE 或旧版 Tomcat 适配可能会出现启动异常。建议用spring-boot-dependenciesBOM 统一管理不要手动管理一大堆传递依赖版本。其次是配置项迁移。像logging.structured这类新配置自然是新的但有些旧配置项在新版本里被标记为 deprecated。我建议升级前跑一遍应用启动日志把所有 “deprecated” 的提示收集起来集中处理而不是等功能出毛病了再回头找。具体到结构化日志的迁移我整理了一张简短的检查单检查项操作确认 Spring Boot 版本3.4.x看 BOM 是否最新确认日志实现默认 Logback日志实现不要混用检查 MDC 使用点确保清理及时避免字段串位检查敏感字段对phone、idCard等做脱敏或过滤检查异步线程池确认 MDC 线程传递方案检查日志采集解析确认不再需要 Grok 等文本解析规则本地开发体验关闭 JSON 或使用独立 profile6.2 什么时候值得改动如果你的项目已经稳定运行日志排查基本靠看文件短期内没有统一采集分析的需求那 Spring Boot 3.4 的结构化日志不是你的必选项升级主要看其他新特性对你有无价值。但如果你的系统正在做容器化改造或者马上要接入某个日志中台那这波改动就很有必要赶在改造前做掉。从我的体会来看结构化日志的最佳落地时机是在一个项目还没被各种文本日志规则绑死的时候。新项目天然适合直接上老项目则需要选一个边界清晰的服务做试点。我们当时选了一个流量不大、链路不算复杂、但日志标准度很差的内部服务做了切换跑了半个月把采集、查询、误报的问题都趟平了之后再往核心服务推阻力就小多了。如果你所在团队还在用System.out打日志那我更建议先从“把日志全部收敛到 Logback”开始直接跳到结构化日志会有点消化不良。万丈高楼平地起日志这种事最好一步步来。我还记得第一次切完一个服务之后在日志平台上按 traceId 查询几秒钟把所有相关日志按照时间线拉出来的那一刻旁边同事说了一句“这比对着文件翻快多了。”真实感受就是这样朴素但直接。技术上它不是那种“看不懂但很高级”的黑魔法它就是把你每天都要做的事换了一个更顺手的方式。后来我给其他团队做分享时总爱说一句话日志写得好不好不是看排版好不好看而是看五分钟之内能不能帮你定位到问题。结构化的本质就是为了让那五分钟再短一点。
阅读完成 · 觉得有帮助？
