logback

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Logback - Quick Reference

Logback - 快速参考

When to Use This Skill

适用场景

  • Configure logging in Spring Boot/Java applications
  • File appender with rotation
  • High-performance async logging
Deep Knowledge: Use
mcp__documentation__fetch_docs
with technology:
logback
for comprehensive documentation.
  • 在Spring Boot/Java应用中配置日志
  • 带轮转功能的文件追加器
  • 高性能异步日志
深度资料: 使用
mcp__documentation__fetch_docs
工具,指定technology为
logback
以获取完整文档。

Configuration

配置

logback-spring.xml (Spring Boot)

logback-spring.xml (Spring Boot)

xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>

    <property name="LOG_PATH" value="${LOG_PATH:-logs}"/>
    <property name="LOG_FILE" value="${LOG_FILE:-app}"/>

    <!-- Console Appender -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}</pattern>
        </encoder>
    </appender>

    <!-- Rolling File Appender -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/${LOG_FILE}.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/${LOG_FILE}.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>30</maxHistory>
            <totalSizeCap>3GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Async Appender -->
    <appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="FILE"/>
        <queueSize>512</queueSize>
        <discardingThreshold>0</discardingThreshold>
    </appender>

    <!-- Logger Configuration -->
    <logger name="com.myapp" level="DEBUG"/>
    <logger name="org.springframework" level="INFO"/>
    <logger name="org.hibernate.SQL" level="DEBUG"/>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="ASYNC"/>
    </root>

    <!-- Profile-specific -->
    <springProfile name="prod">
        <root level="WARN">
            <appender-ref ref="ASYNC"/>
        </root>
    </springProfile>
</configuration>
xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>

    <property name="LOG_PATH" value="${LOG_PATH:-logs}"/>
    <property name="LOG_FILE" value="${LOG_FILE:-app}"/>

    <!-- Console Appender -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}</pattern>
        </encoder>
    </appender>

    <!-- Rolling File Appender -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/${LOG_FILE}.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/${LOG_FILE}.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>30</maxHistory>
            <totalSizeCap>3GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Async Appender -->
    <appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="FILE"/>
        <queueSize>512</queueSize>
        <discardingThreshold>0</discardingThreshold>
    </appender>

    <!-- Logger Configuration -->
    <logger name="com.myapp" level="DEBUG"/>
    <logger name="org.springframework" level="INFO"/>
    <logger name="org.hibernate.SQL" level="DEBUG"/>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="ASYNC"/>
    </root>

    <!-- Profile-specific -->
    <springProfile name="prod">
        <root level="WARN">
            <appender-ref ref="ASYNC"/>
        </root>
    </springProfile>
</configuration>

JSON Format (ELK Stack)

JSON格式(ELK栈)

xml
<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder">
        <includeMdcKeyName>requestId</includeMdcKeyName>
        <includeMdcKeyName>userId</includeMdcKeyName>
    </encoder>
</appender>
xml
<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder">
        <includeMdcKeyName>requestId</includeMdcKeyName>
        <includeMdcKeyName>userId</includeMdcKeyName>
    </encoder>
</appender>

MDC Usage

MDC使用

java
import org.slf4j.MDC;

MDC.put("requestId", UUID.randomUUID().toString());
MDC.put("userId", user.getId());
try {
    // Business logic
} finally {
    MDC.clear();
}
java
import org.slf4j.MDC;

MDC.put("requestId", UUID.randomUUID().toString());
MDC.put("userId", user.getId());
try {
    // Business logic
} finally {
    MDC.clear();
}

When NOT to Use This Skill

不适用场景

  • SLF4J API questions: Focus on API usage, not Logback implementation details
  • Log4j2 configuration: Different XML structure and features
  • Application code logging: Use SLF4J API, Logback is just the implementation
  • Non-Java projects: Use language-appropriate logging frameworks
  • Simple console output: System.out may be sufficient for basic scripts
  • SLF4J API相关问题: 聚焦于API使用,而非Logback实现细节
  • Log4j2配置: 其XML结构和特性与Logback不同
  • 应用代码日志: 应使用SLF4J API,Logback仅为其实现
  • 非Java项目: 使用对应语言的日志框架
  • 简单控制台输出: 基础脚本使用System.out即可满足需求

Anti-Patterns

反模式

Anti-PatternWhy It's BadSolution
Synchronous file appender in high-trafficBlocks application threadsUse
AsyncAppender
wrapper
No rolling policyLogs fill disk spaceUse
RollingFileAppender
with size/time policies
Logging to console in productionPerformance overhead, lost logsUse file appenders, ship to centralized logging
DEBUG level in productionPerformance impact, disk usageUse INFO or WARN in production profiles
Not clearing MDCMemory leaks, wrong context in threadsAlways clear MDC in finally block
Hardcoded log pathsBreaks across environmentsUse properties:
${LOG_PATH}
反模式问题原因解决方案
高流量场景下使用同步文件追加器会阻塞应用线程使用
AsyncAppender
进行包装
未配置轮转策略日志会占满磁盘空间使用带大小/时间策略的
RollingFileAppender
生产环境下输出日志到控制台性能开销大,日志易丢失使用文件追加器,并将日志发送到集中式日志系统
生产环境使用DEBUG级别日志影响性能,占用磁盘空间在生产环境配置文件中使用INFO或WARN级别
未清理MDC导致内存泄漏,线程上下文错误务必在finally块中清理MDC
硬编码日志路径在不同环境下会失效使用属性配置:
${LOG_PATH}

Quick Troubleshooting

快速排查问题

IssueCauseSolution
Configuration not loadedWrong file name/locationUse
logback-spring.xml
in src/main/resources
Logs not rotatingMissing rolling policyAdd
SizeAndTimeBasedRollingPolicy
Performance degradationSynchronous appendersWrap with
AsyncAppender
MDC values not appearingPattern missing MDC placeholdersAdd
%X{key}
to pattern
Duplicate log entriesLogger additivity enabledSet
additivity="false"
on logger
Profile-specific config ignoredUsing logback.xml insteadRename to
logback-spring.xml
for Spring profiles
问题原因解决方案
配置未加载文件名或位置错误在src/main/resources目录下使用
logback-spring.xml
日志未轮转缺少轮转策略添加
SizeAndTimeBasedRollingPolicy
性能下降使用了同步追加器
AsyncAppender
进行包装
MDC值未显示日志格式中缺少MDC占位符在格式中添加
%X{key}
日志重复输出日志记录器的可添加性已启用在日志记录器上设置
additivity="false"
环境特定配置未生效使用了logback.xml而非logback-spring.xml重命名为
logback-spring.xml
以支持Spring环境配置