Java Logback简易教程

一、前言

本文以一个简单的项目为例，一步步展示logback的同步和异步配置方法，并且配置的日志要求满足阿里巴巴Java开发手册-日志规约，因为对于线上服务，日志对于排查问题有至关重要的作用，规范的日志格式配合shell脚本可以快速定位问题。

最开始使用Java日志系统，最大的疑惑就是分不清楚log4j、slf4j、logback等日志库之间的关系，不过网上有不少文章介绍这部分相关知识，比如理解Java日志体系、Java日志框架那些事儿、混乱的 Java 日志体系，可以作为提前阅读。

二、配置同步日志

2.1 日志要求

首先项目的整体结构如下图所示：

一共有两个package，util和http，下面分别有两个类Util.java和Http.java，我们的日志要求是：

http目录下的文件产生的日志全部记录到：~/logs/${appname}/http.log，级别：INFO
util目录下的文件产生的日志全部记录到：~/logs/${appname}/util.log，级别：DEBUG
其余日志文件均记录到：~/logs/${appname}/${appname}.log，级别：INFO
要求所有的日志均至少保存15天
如果保存15天，内容太大可能造成磁盘风险，则最大保存10GB的日志。

2.2 添加POM

使用logback+slf4j的组合，需要依赖的pom如下所示：

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"

         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>com.test</groupId>

    <artifactId>logback-test</artifactId>

    <version>1.0-SNAPSHOT</version>

    <dependencies>

        <dependency>

            <groupId>org.slf4j</groupId>

            <artifactId>slf4j-api</artifactId>

            <version>1.7.10</version>

        </dependency>

        <dependency>

            <groupId>ch.qos.logback</groupId>

            <artifactId>logback-classic</artifactId>

            <version>1.2.3</version>

        </dependency>

    </dependencies>

</project>

2.3 添加logback.xml

logback查找配置的顺序如下所示：

在系统配置文件System Properties中寻找是否有logback.configurationFile对应的value
在classpath下寻找是否有logback.groovy（即logback支持groovy与xml两种配置方式）
在classpath下寻找是否有logback-test.xml
在classpath下寻找是否有logback.xml

在resources目录下添加logback.xml，目前内容为空，如下所示：

<?xml version="1.0" encoding="UTF-8"?>

<configuration>

</configuration>

2.4 配置appender

appender用来配置日志的文件名、日志的写入策略，滚动策略等，我们按照2.1的要求配置appender如下所示：

<?xml version="1.0" encoding="UTF-8"?>

<configuration>

    <property name="APP_NAME" value="logbacktest" />

    <property name="LOG_NAME" value="${user.home}/logs/${APP_NAME}/${APP_NAME}.log" />

    <appender name="APP_LOG" class="ch.qos.logback.core.rolling.RollingFileAppender">

        <!--指定日志文件名称-->

        <file>${LOG_NAME}</file>

        <encoder>

            <!--指定日志内容格式-->

            <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>

            <charset>utf8</charset>

        </encoder>

        <rollingPolicy

                class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">

            <fileNamePattern>${LOG_NAME}.%d{yyyy-MM-dd}.%i.log</fileNamePattern>

            <!--日志最大保存15天-->

            <maxHistory>15</maxHistory>

            <!--日志最大的文件大小-->

            <maxFileSize>100MB</maxFileSize>

            <!--日志最大保存10GB-->

            <totalSizeCap>10GB</totalSizeCap>

        </rollingPolicy>

    </appender>

</configuration>

property可以用来定义变量，我们定义APP_NAME为logbacktest，后面可以用${APP_NAME}来使用这个变量，其它的配置见注释。

2.5 配置root

上面我们定义了appender，定义了日志文件名，日志写入策略，但是现在还有一个问题就是：哪个路径下的日志写入上面定义的appender？是Main.java下的，还是Util.java下的呢？

当然，logback有配置专门去配置路径，这里我们先配置root，即：默认表示所有路径。我们在2.1中的要求是其余日志文件均记录到：~/logs/${appname}/${appname}.log，级别：INFO，我们目前可以通过配置root来满足这个需求，如下：

<?xml version="1.0" encoding="UTF-8"?>

<configuration>

    <property name="APP_NAME" value="logbacktest" />

    <property name="LOG_NAME" value="${user.home}/logs/${APP_NAME}/${APP_NAME}.log" />

    <appender name="APP_LOG" class="ch.qos.logback.core.rolling.RollingFileAppender">

        ...

    </appender>

    <root level="INFO">

        <!--ref表示具体的appender name-->

        <appender-ref ref="APP_LOG" />

    </root>

</configuration>

这样配置之后，所有的日志都会以root的level，即INFO去使用APP_LOG这个appender打印。

2.6 打印日志

编辑Util.java如下所示，打印5个级别的日志：

package com.test.util;

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

/**

 * @author bodong.ybd

 * @date 2019/6/17

 */

public class Util {

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

    public static void loginfo() {

        log.trace("trace");

        log.debug("debug");

        log.info("info");

        log.warn("warn");

        log.error("error");

    }

}

编辑Main.java文件内容如下所示：

package com.test;

import com.test.util.Util;

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

/**

 * @author bodong.ybd

 * @date 2019/6/17

 */

public class Main {

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

    private static void loginfo() {

        log.trace("trace");

        log.debug("debug");

        log.info("info");

        log.warn("warn");

        log.error("error");

    }

    public static void main(String[] args) {

        loginfo();

        Util.loginfo();

    }

}

运行Main.java，打印日志，效果如下：

➜  ~ ls ~/logs/logbacktest

logbacktest.log

➜  ~ cat ~/logs/logbacktest/logbacktest.log

2019-06-19 19:33:26 [main] INFO  com.test.Main - info

2019-06-19 19:33:26 [main] WARN  com.test.Main - warn

2019-06-19 19:33:26 [main] ERROR com.test.Main - error

2019-06-19 19:33:26 [main] INFO  com.test.util.Util - info

2019-06-19 19:33:26 [main] WARN  com.test.util.Util - warn

2019-06-19 19:33:26 [main] ERROR com.test.util.Util - error

可以看到产生了一个日志文件logbacktest.log，并且Main.java和Util.java的日志都打印在了这个文件中，日志级别是root配置的INFO，但是这样并不满足要求，因为2.1要求：util目录下的文件产生的日志全部记录到：~/logs/${appname}/util.log，级别：DEBUG，这个问题需要配置logger来解决。

2.7 配置logger

logger用来设置某个包或者类具体日志的打印级别，下面我们把Util.java配置拆出去。

<?xml version="1.0" encoding="UTF-8"?>

<configuration>

    <property name="APP_NAME" value="logbacktest" />

    <property name="LOG_NAME" value="${user.home}/logs/${APP_NAME}/${APP_NAME}.log" />

    <property name="UTIL_NAME" value="${user.home}/logs/${APP_NAME}/util.log" />

    <appender name="APP_LOG" class="ch.qos.logback.core.rolling.RollingFileAppender">

            ...

            </appender>

    <appender name="UTIL_LOG" class="ch.qos.logback.core.rolling.RollingFileAppender">

        <!--指定日志文件名称-->

        <file>${UTIL_NAME}</file>

        <encoder>

            <!--指定日志内容格式-->

            <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>

            <charset>utf8</charset>

        </encoder>

        <rollingPolicy

                class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">

            <fileNamePattern>${UTIL_NAME}.%d{yyyy-MM-dd}.%i.log</fileNamePattern>

            <!--日志最大保存15天-->

            <maxHistory>15</maxHistory>

            <!--日志最大的文件大小-->

            <maxFileSize>100MB</maxFileSize>

            <!--日志最大保存10GB-->

            <totalSizeCap>10GB</totalSizeCap>

        </rollingPolicy>

    </appender>

    <!--com.test.util目录下的文件产生的日志全部记录到util.log-->

    <!--默认的日志级别是DEBUG-->

    <!--additivity=false表示如果能匹配到这条规则就不用往上继续查找到root节点去-->

    <logger name="com.test.util" level="DEBUG" additivity="false" >

        <appender-ref ref="UTIL_LOG"/>

    </logger>

    <root level="INFO">

        <!--ref表示具体的appender-->

        <appender-ref ref="APP_LOG" />

    </root>

</configuration>

这样配置完成后就可以把Util.java和Main.java的日志分开了，效果如下所示：

➜  ~ ls ~/logs/logbacktest

logbacktest.log util.log

➜  ~ cat ~/logs/logbacktest/logbacktest.log

2019-06-19 19:42:51 [main] INFO  com.test.Main - info

2019-06-19 19:42:51 [main] WARN  com.test.Main - warn

2019-06-19 19:42:51 [main] ERROR com.test.Main - error

➜  ~ cat ~/logs/logbacktest/util.log

2019-06-19 19:42:51 [main] DEBUG com.test.util.Util - debug

2019-06-19 19:42:51 [main] INFO  com.test.util.Util - info

2019-06-19 19:42:51 [main] WARN  com.test.util.Util - warn

2019-06-19 19:42:51 [main] ERROR com.test.util.Util - error

好了，看到这里，详细Http.java相关的日志你肯定也会配置了，试试看。

三、配置异步日志

写入方式	优点	缺点
同步	一般使用O_SYNC标志打开文件，即每条日志会至少写入磁盘缓存，安全。	慢，每条都会刷盘。
异步	将内容写入到内存即可返回（不同异步库可能用不同数据结构），速度快。更多可参考：https://logging.apache.org/log4j/2.x/manual/async.html	不安全，如果内存数据结构满了或者机器断电，可能造成数据丢失。

使用logback配置异步日志可以使用appender：ch.qos.logback.classic.AsyncAppender，将上面的Util.java的log配置为异步如下所示：

<appender name ="ASYNC_UTIL_LOG" class="ch.qos.logback.classic.AsyncAppender">

        <discardingThreshold>0</discardingThreshold>

        <queueSize>512</queueSize>

        <neverBlock>true</neverBlock>

        <appender-ref ref="UTIL_LOG"/>

    </appender>

    <logger name="com.test.util" level="DEBUG" additivity="false" >

        <appender-ref ref="ASYNC_UTIL_LOG"/>

    </logger>

discardingThreshold：默认情况下，当阻塞队列剩余20％的容量时，它将丢弃级别TRACE，DEBUG和INFO的事件，仅保留级别WARN和ERROR的事件。要保留所有事件，请将discardingThreshold设置为0。
queueSize：阻塞队列的最大容量。默认情况下，queueSize设置为256。
neverBlock：如果为false（默认值），appender将阻塞在添加队列的接口处。设置为true，appender将删除消息，不会阻止您的应用程序。
这几个参数更加详细的解释见： https://logback.qos.ch/manual/appenders.html

logback还有另一种异步日志配置方式，即使用disruptor，可参考这里配置。

四、总结

本文以一个例子说明了logback+slf4配置同步和异步日志的方法，使用异步日志除了可以提高程序性能之外，还可以防止部分磁盘IO Hang导致的问题，水平有限，如有不足，请指出。

[完]

巴特西