Java 后端 / 系统课时

设计结构化日志

设计结构化日志

本课把普通文本日志改造成稳定的 JSON 事件,并为每次请求补充请求标识、业务字段和脱敏规则。完成后,日志可以被集中采集、按字段查询,并能在排障时串起同一次请求的关键步骤。

学习目标

  • 设计适合检索和聚合的结构化日志字段
  • 使用 MDC 为请求注入并传递统一请求标识
  • 配置 JSON 输出、日志级别和敏感字段脱敏

先确定日志事件模型

结构化日志不是“把一整句文本放进 JSON”,而是把事件拆成稳定字段。至少应包含时间、级别、服务名、环境、线程、记录器、事件名称和 requestId;业务日志再补充 orderId、customerId、金额或结果码等可检索字段。

字段名一旦进入查询、告警和仪表盘,就应保持稳定。事件名称建议使用机器友好的固定值,例如 order_created,而把自然语言说明留在文档中。密码、令牌、证件号和完整银行卡号不得进入日志。

结构化日志从请求到采集平台的数据流

配置 JSON 输出与日志级别

先加入 Logstash Logback Encoder,它能把 MDC 和结构化参数写入 JSON。示例版本适用于 Spring Boot 3 常见的 Logback 1.4 环境。

xml
<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>7.4</version>
</dependency>

在 application.yml 中按包控制级别,避免把根级别长期设为 DEBUG。生产环境通常保留业务包 INFO,只对短期排障的目标包临时提升级别。

yaml
logging:
  level:
    root: INFO
    com.example.order: INFO
    org.springframework.web: WARN

再创建 src/main/resources/logback-spring.xml。配置将日志写到标准输出,并对常见敏感字段执行掩码。

xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <springProperty
            scope="context"
            name="appName"
            source="spring.application.name"
            defaultValue="order-service"/>

    <appender name="JSON_STDOUT"
              class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
            <customFields>
                {"service":"${appName}","environment":"${APP_ENV:-local}"}
            </customFields>
            <includeMdc>true</includeMdc>
            <jsonGeneratorDecorator
                    class="net.logstash.logback.mask.MaskingJsonGeneratorDecorator">
                <defaultMask>***</defaultMask>
                <path>password</path>
                <path>token</path>
                <path>authorization</path>
            </jsonGeneratorDecorator>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="JSON_STDOUT"/>
    </root>
</configuration>

配置生效后,每条日志独占一行 JSON,便于采集器按行读取。掩码规则只能作为最后一道防线,业务代码仍不应主动记录完整请求对象或认证头。

注入并清理请求标识

过滤器优先接收上游传来的 X-Request-Id;值缺失或格式不合法时生成 UUID。请求结束后必须移除 MDC,防止线程复用导致标识串到下一次请求。

java
package com.example.logging;

import java.io.IOException;
import java.util.Optional;
import java.util.UUID;
import java.util.regex.Pattern;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

@Component
public class RequestIdFilter extends OncePerRequestFilter {

    private static final String HEADER = "X-Request-Id";
    private static final String MDC_KEY = "requestId";
    private static final Pattern SAFE_VALUE =
            Pattern.compile("[A-Za-z0-9._-]{8,64}");

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain)
            throws ServletException, IOException {

        String requestId = Optional.ofNullable(request.getHeader(HEADER))
                .filter(value -> SAFE_VALUE.matcher(value).matches())
                .orElseGet(() -> UUID.randomUUID().toString());

        MDC.put(MDC_KEY, requestId);
        response.setHeader(HEADER, requestId);

        try {
            filterChain.doFilter(request, response);
        } finally {
            // Web 线程会复用,必须清理本次请求写入的上下文。
            MDC.remove(MDC_KEY);
        }
    }
}

MDC 默认依赖当前线程。若任务切换到 @Async、线程池或响应式链路,需要显式传播上下文,不能假设请求线程中的标识会自动出现在线程池日志里。

记录业务字段而不是拼接文本

使用结构化参数记录业务键值,事件名保持固定。下面的服务类不会记录密码、令牌或完整用户对象,只输出排障和统计真正需要的字段。

java
package com.example.order;

import static net.logstash.logback.argument.StructuredArguments.kv;

import java.math.BigDecimal;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;

@Service
public class OrderAuditLogger {

    private static final Logger log =
            LoggerFactory.getLogger(OrderAuditLogger.class);

    public void orderCreated(
            long orderId,
            long customerId,
            BigDecimal amount) {

        log.info(
                "order_created",
                kv("orderId", orderId),
                kv("customerId", customerId),
                kv("amount", amount));
    }
}

不要写成 log.info("用户 {} 创建订单 {}", user, order),因为对象的 toString() 可能意外包含手机号、地址或令牌。对金额、状态和结果码等字段,应使用统一名称与数据类型,避免同一个字段有时是数字、有时又是字符串。

运行并检查输出

启动应用后,向任一受保护的接口发送带请求标识的请求。下面以已有的订单查询接口为例:

bash
curl -i -H 'X-Request-Id: req-20260806-0001' http://localhost:<PORT>/api/orders/<ID>

预期结果:

text
HTTP/1.1 200
X-Request-Id: req-20260806-0001
Content-Type: application/json

当业务代码记录订单事件时,控制台应出现类似的一行 JSON:

json
{"@timestamp":"<TIME>","level":"INFO","logger_name":"com.example.order.OrderAuditLogger","message":"order_created","service":"order-service","environment":"local","requestId":"req-20260806-0001","orderId":<ID>,"customerId":<ID>,"amount":99.90}

实际时间、端口、ID 和字段顺序可能不同。验证重点是输出可被 JSON 解析、requestId 与响应头一致、业务字段保持独立类型,并且敏感字段不会以明文出现。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计结构化日志

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通