Logback Pattern Layout 转换字符完整参考手册

一、基础转换字符

转换字符	别名	含义	示例输出	性能影响
`%d{pattern}`	`%date{pattern}`	日期时间	`2025-12-08 14:30:25.123`	低
`%m`	`%msg`, `%message`	日志消息内容	`用户登录成功`	极低
`%n`	-	平台相关的换行符	`\n` (Unix) 或 `\r\n` (Windows)	极低
`%p`	`%le`, `%level`	日志级别	`INFO`, `DEBUG`, `ERROR`	极低
`%r`	`%relative`	从程序启动到日志创建的毫秒数	`12345`	低
`%t`	`%thread`	线程名称	`main`, `http-nio-8080-exec-1`	低

二、Logger 相关

转换字符	别名	含义	示例输出	说明
`%c{length}`	`%lo{length}`, `%logger{length}`	Logger 名称（可指定长度）	`com.Glowxq.UserService`	length 控制包名缩写
`%C{length}`	`%class{length}`	调用者的完全限定类名	`com.Glowxq.UserService`	⚠️ 性能开销大

Logger 名称长度示例

xml

<!-- 完整名称 -->
%logger → com.Glowxq.base.business.service.UserService

<!-- 只保留类名 -->
%logger{0} → UserService

<!-- 最多保留1段包名 -->
%logger{1} → c.i.b.b.s.UserService

<!-- 保留最后2段 -->
%logger{2} → service.UserService

<!-- 限制总长度为36字符 -->
%logger{36} → c.i.b.b.s.UserService

三、调用位置信息（谨慎使用）

转换字符	别名	含义	示例输出	性能影响
`%C`	`%class`	调用者类的完全限定名	`com.Glowxq.UserService`	⚠️ 极高
`%F`	`%file`	源文件名	`UserService.java`	⚠️ 极高
`%L`	`%line`	代码行号	`127`	⚠️ 极高
`%M`	`%method`	调用的方法名	`login`	⚠️ 极高
`%caller{depth}`	-	调用栈信息	见下方示例	⚠️ 极高

⚠️ 警告: 这些转换字符需要生成堆栈快照，对性能影响极大，生产环境慎用！

%caller 示例

xml

<pattern>%caller{2}</pattern>

输出：

Caller+0   at com.Glowxq.UserService.login(UserService.java:127)
Caller+1   at com.Glowxq.UserController.handleLogin(UserController.java:45)

四、MDC（映射诊断上下文）

转换字符	含义	示例配置	示例输出	说明
`%X{key}`	输出指定 key 的 MDC 值	`%X{userId}`	`user_12345`	常用于分布式追踪
`%X{key:-defaultValue}`	带默认值的 MDC	`%X{traceId:-N/A}`	`abc123` 或 `N/A`	key 不存在时显示默认值
`%mdc{key}`	同 `%X{key}`	`%mdc{requestId}`	`req_789`	别名写法

MDC 使用示例

java

import org.slf4j.MDC;

// 设置 MDC
MDC.put("userId", "user_12345");
MDC.put("traceId", "abc-def-123");
MDC.put("requestId", "req_789");

// 日志会自动带上 MDC 信息
logger.info("用户执行操作");

// 记得清理（避免内存泄漏）
MDC.clear();

配置：

xml

<pattern>%d [%X{traceId}] [%X{userId}] %m%n</pattern>

输出：

2025-12-08 14:30:25.123 [abc-def-123] [user_12345] 用户执行操作

五、异常堆栈

转换字符	别名	含义	配置示例
`%ex`	`%exception`, `%throwable`	完整异常堆栈	`%ex`
`%ex{short}`	-	第一行异常信息	`%ex{short}`
`%ex{full}`	-	完整堆栈（默认）	`%ex{full}`
`%ex{n}`	-	只显示前 n 行堆栈	`%ex{5}`
`%nopex`	`%nopexception`	不输出异常信息	`%nopex`
`%rEx`	`%rootException`	根异常（跳过包装异常）	`%rEx`
`%xEx`	`%xException`	扩展异常信息（带 jar 信息）	`%xEx`

异常堆栈示例

xml

<!-- 只显示前3行堆栈 -->
<pattern>%d %p %c - %m%n%ex{3}</pattern>

<!-- 显示完整堆栈，但过滤某些包 -->
<pattern>%d %p %c - %m%n%ex{full, 
    sun.reflect,
    java.lang.reflect,
    org.apache.catalina
}</pattern>

六、格式修饰符

6.1 宽度控制

格式	含义	示例	输出（假设内容是 "INFO"）
`%20p`	最小宽度 20，右对齐	`%20p`	`INFO`
`%-20p`	最小宽度 20，左对齐	`%-20p`	`INFO`
`%.30p`	最大宽度 30，超出截断（从左边）	`%.30p`	`INFO`
`%.-30p`	最大宽度 30，超出截断（从右边）	`%.-30p`	`INFO`
`%20.30p`	最小 20，最大 30	`%20.30p`	根据实际长度调整

6.2 颜色高亮（仅控制台）

转换字符	含义	示例配置
`%black()`	黑色	`%black(%m)`
`%red()`	红色	`%red(%p)`
`%green()`	绿色	`%green(%m)`
`%yellow()`	黄色	`%yellow(%p)`
`%blue()`	蓝色	`%blue(%logger)`
`%magenta()`	洋红色	`%magenta(%t)`
`%cyan()`	青色	`%cyan(%d)`
`%white()`	白色	`%white(%m)`
`%gray()`	灰色	`%gray(%logger)`
`%highlight()`	根据日志级别自动高亮	`%highlight(%p)`

彩色日志示例

xml

<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
        <pattern>%cyan(%d{HH:mm:ss.SSS}) %highlight(%-5level) [%blue(%t)] %yellow(%logger{36}) - %msg%n</pattern>
    </encoder>
</appender>

效果：

时间：青色
级别：根据级别自动着色（ERROR 红色，WARN 黄色，INFO 绿色等）
线程：蓝色
Logger：黄色

七、特殊转换字符

转换字符	含义	示例输出	说明
`%property{key}`	输出配置文件中的属性	-	读取 `<property>` 定义的值
`%replace(p){regex, replacement}`	正则替换	见下方	用于脱敏等场景
`%-5(...)`	给组合内容应用格式	-	可以给多个转换字符整体应用格式

%property 示例

xml

<configuration>
    <property name="APP_NAME" value="Glowxq-base"/>
    
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>[%property{APP_NAME}] %d %p - %m%n</pattern>
        </encoder>
    </appender>
</configuration>

输出：

[Glowxq-base] 2025-12-08 14:30:25.123 INFO - 用户登录成功

%replace 示例（日志脱敏）

xml

<!-- 手机号脱敏：将中间4位替换为 **** -->
<pattern>%replace(%m){'(\d{3})\d{4}(\d{4})', '$1****$2'}%n</pattern>

输入日志：

java

logger.info("用户手机号：13812345678");

输出：

用户手机号：138****5678

八、常用组合配置示例

8.1 简洁开发环境配置

xml

<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} %5p [%t] %logger{36} - %m%n</pattern>
        </encoder>
    </appender>
    
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

8.2 彩色控制台（适合本地开发）

xml

<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%cyan(%d{HH:mm:ss.SSS}) %highlight(%-5level) [%blue(%t)] %yellow(%C{1}.%M:%L) - %msg%n%ex{5}</pattern>
        </encoder>
    </appender>
    
    <root level="DEBUG">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

8.3 生产环境完整配置（带分布式追踪）

xml

<configuration>
    <property name="LOG_PATTERN" 
              value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{traceId:-N/A}] [%X{spanId:-N/A}] %5p [%t] %-40.40logger{39} : %m%n"/>
    
    <!-- 控制台输出 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>${LOG_PATTERN}</pattern>
        </encoder>
    </appender>
    
    <!-- 文件输出（带滚动） -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logs/application.log</file>
        <encoder>
            <pattern>${LOG_PATTERN}</pattern>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>logs/application.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
            <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
                <maxFileSize>100MB</maxFileSize>
            </timeBasedFileNamingAndTriggeringPolicy>
            <maxHistory>30</maxHistory>
        </rollingPolicy>
    </appender>
    
    <!-- ERROR 单独文件 -->
    <appender name="ERROR_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logs/error.log</file>
        <filter class="ch.qos.logback.classic.filter.LevelFilter">
            <level>ERROR</level>
            <onMatch>ACCEPT</onMatch>
            <onMismatch>DENY</onMismatch>
        </filter>
        <encoder>
            <pattern>${LOG_PATTERN}%ex{full}</pattern>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>logs/error.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>90</maxHistory>
        </rollingPolicy>
    </appender>
    
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="FILE"/>
        <appender-ref ref="ERROR_FILE"/>
    </root>
</configuration>

8.4 JSON 格式日志（适合日志采集）

xml

<configuration>
    <appender name="JSON_CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
            <customFields>{"app":"Glowxq-base","env":"prod"}</customFields>
        </encoder>
    </appender>
    
    <root level="INFO">
        <appender-ref ref="JSON_CONSOLE"/>
    </root>
</configuration>

需要添加依赖：

xml

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

输出示例：

json

{
  "@timestamp": "2025-12-08T14:30:25.123+08:00",
  "message": "用户登录成功",
  "logger_name": "com.Glowxq.UserService",
  "thread_name": "http-nio-8080-exec-1",
  "level": "INFO",
  "app": "Glowxq-base",
  "env": "prod",
  "traceId": "abc123",
  "spanId": "span789"
}

九、性能优化建议

9.1 性能影响对比

转换字符	性能影响	建议
`%m`, `%p`, `%t`, `%d`	极低	✅ 放心使用
`%c`, `%logger`	低	✅ 推荐使用
`%X` (MDC)	低-中	✅ 推荐用于追踪
`%r`	低	✅ 可以使用
`%C`, `%F`, `%L`, `%M`	极高	⚠️ 仅调试环境
`%caller`	极高	⚠️ 仅调试环境

9.2 生产环境最佳实践

xml

<!-- ✅ 推荐：高性能配置 -->
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{traceId}] %5p [%t] %logger{36} - %m%n</pattern>

<!-- ❌ 不推荐：性能杀手 -->
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %5p [%t] %C.%M:%L - %m%n</pattern>

9.3 异步日志配置

xml

<configuration>
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>app.log</file>
        <encoder>
            <pattern>%d %p %c - %m%n</pattern>
        </encoder>
    </appender>
    
    <!-- 异步包装器 -->
    <appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="FILE"/>
        <queueSize>512</queueSize>
        <discardingThreshold>0</discardingThreshold>
    </appender>
    
    <root level="INFO">
        <appender-ref ref="ASYNC_FILE"/>
    </root>
</configuration>

十、调试技巧

10.1 查看实际使用的配置

在 Java 代码中：

java

import ch.qos.logback.classic.LoggerContext;
import org.slf4j.LoggerFactory;

LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();
StatusPrinter.print(lc);

10.2 配置文件调试

xml

<configuration debug="true">
    <!-- 会在启动时打印 Logback 的配置解析过程 -->
</configuration>

十一、常见问题

Q1: 日志中中文乱码？

xml

<encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
    <charset>UTF-8</charset>
    <layout class="ch.qos.logback.classic.PatternLayout">
        <pattern>%d %p %c - %m%n</pattern>
    </layout>
</encoder>

Q2: 如何在日志中输出 `%` 符号？

使用 %% 转义：

xml

<pattern>进度: %%d{HH:mm:ss} - %m%n</pattern>

Q3: MDC 在多线程环境下丢失？

使用 MDCTaskDecorator 或 TransmittableThreadLocal：

java

@Bean
public TaskExecutor taskExecutor() {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setTaskDecorator(new MDCTaskDecorator());
    return executor;
}

class MDCTaskDecorator implements TaskDecorator {
    @Override
    public Runnable decorate(Runnable runnable) {
        Map<String, String> contextMap = MDC.getCopyOfContextMap();
        return () -> {
            if (contextMap != null) {
                MDC.setContextMap(contextMap);
            }
            try {
                runnable.run();
            } finally {
                MDC.clear();
            }
        };
    }
}

参考资源

官方文档: https://logback.qos.ch/manual/layouts.html
GitHub: https://github.com/qos-ch/logback
SLF4J 文档: https://www.slf4j.org/manual.html

文档版本: 1.0
适用 Logback 版本: 1.2.x - 1.5.x
最后更新: 2025-12-08

Logback Pattern Layout 转换字符完整参考手册 ​

一、基础转换字符 ​

二、Logger 相关 ​

Logger 名称长度示例 ​

三、调用位置信息（谨慎使用） ​

%caller 示例 ​

四、MDC（映射诊断上下文） ​

MDC 使用示例 ​

五、异常堆栈 ​

异常堆栈示例 ​

六、格式修饰符 ​

6.1 宽度控制 ​

6.2 颜色高亮（仅控制台） ​

彩色日志示例 ​

七、特殊转换字符 ​

%property 示例 ​

%replace 示例（日志脱敏） ​

八、常用组合配置示例 ​

8.1 简洁开发环境配置 ​

8.2 彩色控制台（适合本地开发） ​

8.3 生产环境完整配置（带分布式追踪） ​

8.4 JSON 格式日志（适合日志采集） ​

九、性能优化建议 ​

9.1 性能影响对比 ​

9.2 生产环境最佳实践 ​

9.3 异步日志配置 ​

十、调试技巧 ​

10.1 查看实际使用的配置 ​

10.2 配置文件调试 ​

十一、常见问题 ​

Q1: 日志中中文乱码？ ​

Q2: 如何在日志中输出 % 符号？ ​

Q3: MDC 在多线程环境下丢失？ ​

参考资源 ​

Logback Pattern Layout 转换字符完整参考手册

一、基础转换字符

二、Logger 相关

Logger 名称长度示例

三、调用位置信息（谨慎使用）

%caller 示例

四、MDC（映射诊断上下文）

MDC 使用示例

五、异常堆栈

异常堆栈示例

六、格式修饰符

6.1 宽度控制

6.2 颜色高亮（仅控制台）

彩色日志示例

七、特殊转换字符

%property 示例

%replace 示例（日志脱敏）

八、常用组合配置示例

8.1 简洁开发环境配置

8.2 彩色控制台（适合本地开发）

8.3 生产环境完整配置（带分布式追踪）

8.4 JSON 格式日志（适合日志采集）

九、性能优化建议

9.1 性能影响对比

9.2 生产环境最佳实践

9.3 异步日志配置

十、调试技巧

10.1 查看实际使用的配置

10.2 配置文件调试

十一、常见问题

Q1: 日志中中文乱码？

Q2: 如何在日志中输出 `%` 符号？

Q3: MDC 在多线程环境下丢失？

参考资源