日志是系统问题排查、运行监控的核心依据，规范的日志打印不仅能提升问题定位效率，还能避免资源浪费与安全风险。本文基于基础日志规约，拓展 Trace 级别日志打印、多线程日志处理、父子线程链路传递，并给出与 SkyWalking 框架的整合方案，形成完整的日志实践指南。
一、基础日志规约总结
首先明确日常开发中必须遵守的核心规范，避免基础错误，保障日志的可用性与安全性。
| 规约要点 | 核心要求 | 关键原因 |
|---|---|---|
| 日志框架依赖 | 统一使用 SLF4J 门面 API，不直接调用 Log4j/Logback 原生 API | 降低框架耦合，便于后续切换日志实现（如从 Log4j 迁移到 Logback） |
| 日志级别使用 | 按重要性分级：TRACE（链路）→DEBUG（调试）→INFO（关键）→WARN（风险）→ERROR（错误，触发报警） | 避免日志泛滥，便于按级别过滤信息（如生产环境只输出 INFO 及以上） |
| 字符串拼接 | 必须使用{}占位符，禁止字符串+拼接 | 减少不必要的字符串运算开销（未达到日志级别时，占位符不执行拼接） |
| 耗时操作判断 | TRACE/DEBUG/INFO 级日志，若参数含方法调用或耗时操作，需先判断日志开关 | 避免无意义的方法调用（如debug(getUser())），降低性能损耗 |
| 重复日志避免 | 日志配置中设置additivity=false | 防止父子 Logger 重复打印，节省磁盘空间 |
| 禁止违规输出 | 生产环境禁用System.out/System.err/e.printStackTrace() | 此类输出无级别控制，且无法纳入日志框架统一管理，易丢失信息 |
| 异常日志记录 | 需包含 “案发现场信息（参数、操作）+ 异常堆栈”，不处理则向上抛出 | 仅记录e.getMessage()会丢失堆栈，无法定位异常根源 |
| 敏感信息防护 | 禁止打印密码、手机号、身份证等敏感数据 | 避免日志泄露导致的安全风险，需对敏感字段脱敏（如password: ****） |
| 安全打印校验 | 若对象get方法重写后可能抛异常，打印前需规避 | 防止日志打印触发异常，影响正常业务流程（如user.getRiskInfo()可能抛空指针） |
二、高级拓展：关键场景日志实践
1. Trace 级别日志：如何正确打印？
Trace 级别日志定位为 “链路追踪信息”，用于记录请求从入口到出口的完整路径（如接口调用顺序、参数传递、耗时统计），通常需结合链路追踪框架（如 SkyWalking、Zipkin）使用，单独打印无意义。
打印原则
- 粒度控制：只记录关键链路节点，不打印重复或冗余信息（如每个方法的入参、出参，核心步骤耗时）；
- 上下文关联：需包含链路标识（如 Trace ID、Span ID），确保跨线程、跨服务时能串联链路；
- 开关控制：Trace 级别日志输出量较大，生产环境默认关闭，仅在需要排查链路问题时临时开启。
代码示例（结合 SLF4J）
java
运行
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class OrderService {private static final Logger logger = LoggerFactory.getLogger(OrderService.class);public void createOrder(OrderDTO orderDTO) {// 1. 打印链路入口：包含Trace ID（后续整合SkyWalking后自动注入）、入参if (logger.isTraceEnabled()) {logger.trace("OrderService.createOrder start | traceId: {} | orderDTO: {}",MDC.get("traceId"), orderDTO.toString());}try {// 2. 核心业务步骤：打印关键节点耗时（示例：计算订单金额）long start = System.currentTimeMillis();BigDecimal amount = calculateAmount(orderDTO);if (logger.isTraceEnabled()) {logger.trace("OrderService.calculateAmount end | cost: {}ms | amount: {}",System.currentTimeMillis() - start, amount);}// 3. 调用下游服务（如支付服务）：记录服务调用信息paymentService.pay(amount, orderDTO.getUserId());} catch (Exception e) {// 4. 异常链路记录：包含链路ID和异常堆栈logger.error("OrderService.createOrder failed | traceId: {} | orderDTO: {}",MDC.get("traceId"), orderDTO.toString(), e);throw e;}// 5. 打印链路出口：记录出参或结果if (logger.isTraceEnabled()) {logger.trace("OrderService.createOrder end | traceId: {} | result: success",MDC.get("traceId"));}}
}2. 多线程场景：日志如何打印？
多线程环境下，默认日志无法关联 “父线程与子线程” 的链路关系，且易出现日志混乱（如不同线程日志交叉打印），需通过MDC（Mapped Diagnostic Context，映射诊断上下文） 传递链路信息，并确保日志输出包含线程标识。
核心方案：MDC 传递链路信息
MDC 是 SLF4J 提供的线程本地存储工具，可存储当前线程的链路信息（如 Trace ID、UserId），日志输出时通过配置自动携带这些信息；子线程需手动拷贝父线程的 MDC 上下文，否则会丢失链路关联。
多线程日志打印步骤
- 父线程设置 MDC：在请求入口（如 Controller 层）将链路信息存入 MDC；
- 子线程拷贝 MDC：通过
MDC.getCopyOfContextMap()获取父线程 MDC，在子线程中通过MDC.setContextMap()设置； - 日志配置关联线程信息：在日志输出格式中加入
%X{traceId}（MDC 中的链路 ID）和%t（线程名），确保日志可追溯。
代码示例（多线程 + MDC）
java
运行
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import java.util.Map;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
public class ThreadLogDemo {private static final Logger logger = LoggerFactory.getLogger(ThreadLogDemo.class);private static final ExecutorService executor = Executors.newFixedThreadPool(3);public static void main(String[] args) {// 1. 父线程：请求入口设置MDC（实际项目中由链路框架自动注入，如SkyWalking）MDC.put("traceId", "trace-123456"); // 链路唯一标识MDC.put("userId", "user-789"); // 业务标识（如当前登录用户）logger.info("Parent thread start | 准备提交子任务");// 2. 提交子任务：手动拷贝父线程MDC上下文Map parentMdc = MDC.getCopyOfContextMap(); // 获取父线程MDCexecutor.submit(() -> {try {// 子线程：设置父线程的MDC上下文if (parentMdc != null) {MDC.setContextMap(parentMdc);}// 3. 子线程打印日志：自动携带MDC中的traceId和userIdlogger.debug("Child thread executing | 子线程处理任务");// 模拟业务操作Thread.sleep(100);logger.info("Child thread end | 子任务处理完成");} catch (InterruptedException e) {logger.error("Child thread error | 子任务执行异常", e);} finally {// 4. 子线程结束：清除MDC（避免线程池复用导致MDC污染）MDC.clear();}});// 5. 父线程结束：清除MDCMDC.clear();executor.shutdown();}
} 日志输出格式配置（以 Logback 为例）
在logback.xml中配置日志模板，确保包含线程名和 MDC 信息：
xml
%d{yyyy-MM-dd HH:mm:ss} [%t] %-5level %logger{36} - %msg [traceId:%X{traceId}, userId:%X{userId}]%n 输出结果（链路关联清晰）
plaintext
2024-05-20 15:30:00 [main] INFO com.demo.ThreadLogDemo - Parent thread start | 准备提交子任务 [traceId:trace-123456, userId:user-789]
2024-05-20 15:30:00 [pool-1-thread-1] DEBUG com.demo.ThreadLogDemo - Child thread executing | 子线程处理任务 [traceId:trace-123456, userId:user-789]
2024-05-20 15:30:00 [pool-1-thread-1] INFO com.demo.ThreadLogDemo - Child thread end | 子任务处理完成 [traceId:trace-123456, userId:user-789]3. 父子线程链路传递：自动化方案
手动拷贝 MDC 存在重复代码、易遗漏的问题，可通过线程池包装或AOP 拦截实现 MDC 自动传递，减少重复开发。
方案 1：自定义线程池（自动传递 MDC）
封装ThreadPoolExecutor，在提交任务时自动拷贝父线程 MDC：
java
运行
import org.slf4j.MDC;
import java.util.Map;
import java.util.concurrent.*;
public class MdcThreadPoolExecutor extends ThreadPoolExecutor {// 构造方法（与ThreadPoolExecutor一致）public MdcThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime,TimeUnit unit, BlockingQueue workQueue) {super(corePoolSize, maximumPoolSize, keepAliveTime, unit, workQueue);}// 重写submit方法：包装任务，自动传递MDC@Overridepublic Future submit(Callable task) {// 获取父线程MDCMap parentMdc = MDC.getCopyOfContextMap();// 包装任务：执行前设置MDC，执行后清除Callable mdcTask = () -> {try {if (parentMdc != null) {MDC.setContextMap(parentMdc);}return task.call(); // 执行原任务} finally {MDC.clear();}};return super.submit(mdcTask);}// 重载submit（Runnable版本）@Overridepublic Future submit(Runnable task) {Map parentMdc = MDC.getCopyOfContextMap();Runnable mdcRunnable = () -> {try {if (parentMdc != null) {MDC.setContextMap(parentMdc);}task.run();} finally {MDC.clear();}};return super.submit(mdcRunnable);}
} 使用方式（无需手动处理 MDC）
java
运行
// 创建自定义线程池
ExecutorService mdcExecutor = new MdcThreadPoolExecutor(3, 5, 60, TimeUnit.SECONDS, new LinkedBlockingQueue<>());
// 父线程设置MDC
MDC.put("traceId", "trace-7890");
// 提交任务：自动传递MDC
mdcExecutor.submit(() -> {logger.info("子线程自动携带MDC | traceId已传递"); // 日志会包含traceId:trace-7890
});
MDC.clear();
mdcExecutor.shutdown();三、整合 SkyWalking：实现全链路日志追踪
SkyWalking 是开源 APM（应用性能监控）工具，可自动采集服务调用链路、性能指标，并与日志关联，实现 “日志 - 链路 - 指标” 一体化追踪。整合核心是让 SkyWalking 自动注入 Trace ID 到 MDC，无需手动维护链路信息。
1. 整合前提
- 环境：JDK 8+、Spring Boot 2.x+（以 Spring Boot 项目为例）；
- 依赖：引入 SkyWalking Agent 和日志适配依赖；
- 部署：已搭建 SkyWalking OAP Server（用于接收链路数据）和 UI（用于查看链路）。
2. 具体整合步骤
步骤 1：引入 SkyWalking 依赖（Maven）
在pom.xml中添加 SkyWalking 日志适配依赖（确保与 SkyWalking Agent 版本一致，如 8.16.0）：
xml
org.apache.skywalking apm-toolkit-logback-1.x 8.16.0
org.apache.skywalking apm-toolkit-trace 8.16.0
步骤 2：配置 Logback（关联 SkyWalking Trace ID）
修改logback.xml，通过 SkyWalking 提供的TraceIdPatternLogbackLayout自动注入 Trace ID，无需手动设置 MDC：
xml
%d{yyyy-MM-dd HH:mm:ss} [%t] %-5level %logger{36} - %msg [traceId:%traceId]%n logs/app.log logs/app.%d{yyyy-MM-dd}.log 30 %d{yyyy-MM-dd HH:mm:ss} [%t] %-5level %logger{36} - %msg [traceId:%traceId]%n 步骤 3：配置 SkyWalking Agent
- 下载 SkyWalking Agent 压缩包（从SkyWalking 官网下载，版本与依赖一致）；
- 解压后，在项目启动参数中添加 Agent 配置（以 IDEA 为例，或在服务器启动脚本中配置）：
plaintext
-javaagent:D:\skywalking-agent\skywalking-agent.jar
-Dskywalking.agent.service_name=order-service # 当前服务名（在SkyWalking UI中显示）
-Dskywalking.collector.backend_service=127.0.0.1:11800 # SkyWalking OAP Server地址步骤 4：验证整合效果
- 启动项目和 SkyWalking OAP Server、UI；
- 发起一个请求（如调用
/api/order/create接口）； - 查看日志输出：日志中会自动包含
traceId（由 SkyWalking 生成）；plaintext
2024-05-20 16:00:00 [http-nio-8080-exec-1] INFO com.demo.OrderController - 接收创建订单请求 [traceId:8f7d6c5b-4a3b-2c1d-0e9f-8a7b6c5d4e3f] 2024-05-20 16:00:00 [http-nio-8080-exec-1] INFO com.demo.OrderService - 订单创建成功 [traceId:8f7d6c5b-4a3b-2c1d-0e9f-8a7b6c5d4e3f] - 在 SkyWalking UI 中查询：通过日志中的
traceId，可在 SkyWalking “链路追踪” 页面找到完整的调用链路（包括服务调用顺序、耗时、异常信息）。
3. 高级用法：手动获取 SkyWalking Trace ID
若需在业务代码中手动使用 Trace ID（如返回给前端），可通过TraceContext工具类获取：
java
运行
import org.apache.skywalking.apm.toolkit.trace.TraceContext;
@RestController
@RequestMapping("/api/order")
public class OrderController {private static final Logger logger = LoggerFactory.getLogger(OrderController.class);@PostMapping("/create")public ResponseEntity createOrder(@RequestBody OrderDTO orderDTO) {// 手动获取SkyWalking生成的Trace IDString traceId = TraceContext.traceId();logger.info("创建订单请求 | traceId:{} | orderDTO:{}", traceId, orderDTO);// 业务处理...OrderVO orderVO = orderService.createOrder(orderDTO);// 可选：将Trace ID返回给前端，便于问题排查orderVO.setTraceId(traceId);return ResponseEntity.ok(orderVO);}
} 四、总结
日志规范的核心是 “可追溯、无冗余、保安全”：基础规约保障日志的可用性，Trace 级别日志与 SkyWalking 整合实现全链路追踪，多线程 MDC 传递解决跨线程链路关联问题。实际项目中，需结合业务场景选择合适的日志级别，通过自动化工具（如 SkyWalking、自定义线程池）减少重复开发，同时严格防护敏感信息，确保日志成为系统稳定运行的 “守护者”。
C. Ultimate Value)
