1 概述
logback.xml配置文件的详细配置,很多地方都说得比较细,本文主要从几个重点来看一下原理,了解原理能够帮助确定哪些应该配置,以及如何配置。
logback.xml是为打印日志服务的,打印的内容一般打印到控制台(Console)和文件(file)里,在生产环境中主要是打印到文件里,然后用扫描工具汇总到某个地方方便查询(如ELK)。打印的内容要符合一定的格式,提供足够的信息,方便进行日志查询和分析;如果所有日志都打印到一个文件里,就有可能文件过大而难以查看,还可能大到一个磁盘装不下,也很难把早期的日志删除掉仅保留一定期限内的日志,所以需要对日志文件进行拆分,每个文件确定在一定大小之内,并控制总体仅保留一定量的日志,避免日志总量过多把磁盘占满了宕机等。日志配置文件也不是一成不变的,当修改了配置文件,希望能够不需要重启Java进程而能够生效,比如修改日志级别。
2 原理
2.1 打印内容的格式
XML
<appender name="console" class="ch.qos.logback.core.ConsoleAppender">
<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
<Pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %highlight(%-5level) [%thread] %logger{50} - %msg%n</Pattern>
<charset>UTF-8</charset>
</encoder>
</appender>

上面就是一个<appender>的配置,里面的<Pattern>就是日志内容的格式,还可以设置高亮颜色。如果要详细看logback支持的格式,那么可以参考官方文档:https://logback.qos.ch/manual/layouts.html
如果想了解原理也容易,上面就指明了对应的类ch.qos.logback.classic.encoder.PatternLayoutEncoder,这也代表着甚至可以通过它来自定义。
java
// 当加载logback.xml文件时,解析到<encoder>节点的时候,会调PatternLayoutEncoder.start()
// 源码位置:ch.qos.logback.classic.encoder.PatternLayoutEncoder
public class PatternLayoutEncoder extends PatternLayoutEncoderBase<ILoggingEvent> {
public PatternLayoutEncoder() {
}
public void start() {
// 1. 初始化PatternLayout,里面会初始化一些Converter
PatternLayout patternLayout = new PatternLayout();
patternLayout.setContext(this.context);
patternLayout.setPattern(this.getPattern());
patternLayout.setOutputPatternAsHeader(this.outputPatternAsHeader);
patternLayout.start();
this.layout = patternLayout;
super.start();
}
}
// 源码位置:ch.qos.logback.classic.PatternLayout
// 2. 静态代码块初始化converter,它们决定了<Pattern>节点里能够配置的变量,用%来指示变量,比如%d表示时间
public static final Map<String, String> DEFAULT_CONVERTER_MAP = new HashMap<String, String>();
static {
DEFAULT_CONVERTER_MAP.putAll(Parser.DEFAULT_COMPOSITE_CONVERTER_MAP);
DEFAULT_CONVERTER_MAP.put("d", DateConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("date", DateConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("r", RelativeTimeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("relative", RelativeTimeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("level", LevelConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("le", LevelConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("p", LevelConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("t", ThreadConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("thread", ThreadConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("lo", LoggerConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("logger", LoggerConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("c", LoggerConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("m", MessageConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("msg", MessageConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("message", MessageConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("C", ClassOfCallerConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("class", ClassOfCallerConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("M", MethodOfCallerConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("method", MethodOfCallerConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("L", LineOfCallerConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("line", LineOfCallerConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("F", FileOfCallerConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("file", FileOfCallerConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("X", MDCConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("mdc", MDCConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("ex", ThrowableProxyConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("exception", ThrowableProxyConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("rEx", RootCauseFirstThrowableProxyConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("rootException", RootCauseFirstThrowableProxyConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("throwable", ThrowableProxyConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("xEx", ExtendedThrowableProxyConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("xException", ExtendedThrowableProxyConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("xThrowable", ExtendedThrowableProxyConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("nopex", NopThrowableInformationConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("nopexception", NopThrowableInformationConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("cn", ContextNameConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("contextName", ContextNameConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("caller", CallerDataConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("marker", MarkerConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("property", PropertyConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("n", LineSeparatorConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("black", BlackCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("red", RedCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("green", GreenCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("yellow", YellowCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("blue", BlueCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("magenta", MagentaCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("cyan", CyanCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("white", WhiteCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("gray", GrayCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("boldRed", BoldRedCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("boldGreen", BoldGreenCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("boldYellow", BoldYellowCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("boldBlue", BoldBlueCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("boldMagenta", BoldMagentaCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("boldCyan", BoldCyanCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("boldWhite", BoldWhiteCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("highlight", HighlightingCompositeConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("lsn", LocalSequenceNumberConverter.class.getName());
DEFAULT_CONVERTER_MAP.put("prefix", PrefixCompositeConverter.class.getName());
}
public Map<String, String> getDefaultConverterMap() {
return DEFAULT_CONVERTER_MAP;
}
// 回到PatternLayoutEncoder,继续初始化
// 源码位置:ch.qos.logback.classic.encoder.PatternLayoutEncoder
public class PatternLayoutEncoder extends PatternLayoutEncoderBase<ILoggingEvent> {
public PatternLayoutEncoder() {
}
public void start() {
// 1. 初始化PatternLayout,里面会初始化一些Converter,细节看1.1
PatternLayout patternLayout = new PatternLayout();
patternLayout.setContext(this.context);
patternLayout.setPattern(this.getPattern());
patternLayout.setOutputPatternAsHeader(this.outputPatternAsHeader);
// 3. 开始解析pattern,实际调用的是PatternLayout父类PatternLayoutBase的start()方法
patternLayout.start();
this.layout = patternLayout;
super.start();
}
}
// 继承关系:PatternLayoutEncoder < PatternLayoutBase
// 源码位置:ch.qos.logback.core.pattern.PatternLayoutBase
public void start() {
if (pattern == null || pattern.length() == 0) {
addError("Empty or null pattern.");
return;
}
try {
Parser<E> p = new Parser<E>(pattern);
if (getContext() != null) {
p.setContext(getContext());
}
Node t = p.parse();
// 4. 解析pattern,getEffectiveConverterMap()里面调了步骤2的getDefaultConverterMap()得到了初始化的converter
this.head = p.compile(t, getEffectiveConverterMap());
if (postCompileProcessor != null) {
postCompileProcessor.process(context, head);
}
ConverterUtil.setContextForConverters(getContext(), head);
ConverterUtil.startConverters(this.head);
super.start();
} catch (ScanException sce) {
StatusManager sm = getContext().getStatusManager();
sm.add(new ErrorStatus("Failed to parse pattern \"" + getPattern() + "\".", this, sce));
}
}
// 源码位置:ch.qos.logback.core.pattern.parser.Parser
public Converter<E> compile(final Node top, Map converterMap) {
Compiler<E> compiler = new Compiler<E>(top, converterMap);
compiler.setContext(context);
// compiler.setStatusManager(statusManager);
// 5. 实际解析pattern
return compiler.compile();
}
// 源码位置:ch.qos.logback.core.pattern.parser.Compiler
// 实际解析pattern,整个pattern已经被分成一个个Node,Node的格式如下:
// 以pattern=%d{yyyy-MM-dd HH:mm:ss.SSS}a b c%highlight(%-5level) [%thread] %logger{50} - %msg%n 为例:
// 1) 以%作为开始字符、以})和空格等作为结束字符作为一段进行分割成多段,开始字符和结束字符之间的字符作为一个Keyword Node,段之间如果还有非空字符则作为Literal Node;
// 上例中%d{yyyy-MM-dd HH:mm:ss.SSS}作为Keyword Node,a b c为Literal Node;
// 2) 如果只有一个关键字的则是Simple Keyword Node,如%d{yyyy-MM-dd HH:mm:ss.SSS}
// 如果有多个关键字嵌套的则是Composite Keyword Node,如%highlight(%-5levelx)
// 3) %后面的关键字要能够从converterMap取到,通过它能够从里面找到对应的Converter(参考步骤2),如果找不到就报错了;
// 4) 关键字前面的是format信息,后面的是option信息,
// 比如:%d{yyyy-MM-dd HH:mm:ss.SSS}中,yyyy-MM-dd HH:mm:ss.SSS是option信息,无format信息;
// 比如:%-5level中,5是format信息,表示最短5字符,无option信息;
// 5) 嵌套结构用childNode表示,如%highlight(%-5level)中,%-5level是一个childNode,格式和Node一样;
// 6) 每个Node都有个next,指向下一个节点,即链式结构,通过一层层的next可以遍历整条链;
// 下面最终都是把Converter放到Node里,实际上pattern里的信息都已经分解到Converter里了,打印日志的时候可以直接使用
Converter<E> compile() {
head = tail = null;
// 当n = n.next为null时,链条结束
for (Node n = top; n != null; n = n.next) {
switch (n.type) {
case Node.LITERAL: // Literal Node
addToList(new LiteralConverter<E>((String) n.getValue()));
break;
case Node.COMPOSITE_KEYWORD: // Composite Keyword Node
CompositeNode cn = (CompositeNode) n;
// 根据keyword找到Converter,并进行实例化
CompositeConverter<E> compositeConverter = createCompositeConverter(cn);
if (compositeConverter == null) {
addError("Failed to create converter for [%" + cn.getValue() + "] keyword");
addToList(new LiteralConverter<E>("%PARSER_ERROR[" + cn.getValue() + "]"));
break;
}
// 把信息设置到Converter里
compositeConverter.setFormattingInfo(cn.getFormatInfo());
compositeConverter.setOptionList(cn.getOptions());
// 再处理childNode的Converter
Compiler<E> childCompiler = new Compiler<E>(cn.getChildNode(), converterMap);
childCompiler.setContext(context);
Converter<E> childConverter = childCompiler.compile();
compositeConverter.setChildConverter(childConverter); // 记录childNode的Converter
addToList(compositeConverter); // 记录当前node的Converter
break;
case Node.SIMPLE_KEYWORD: // Simple Keyword Node
SimpleKeywordNode kn = (SimpleKeywordNode) n;
// 根据keyword找到Converter,并进行实例化,主要是Convert的具体类不一样,所以需要多写一个
DynamicConverter<E> dynaConverter = createConverter(kn);
if (dynaConverter != null) {
// 把信息设置到Converter里
dynaConverter.setFormattingInfo(kn.getFormatInfo());
dynaConverter.setOptionList(kn.getOptions());
addToList(dynaConverter); // 记录当前node的Converter
} else {
// 没有对应的Converter则报错
Converter<E> errConveter = new LiteralConverter<E>("%PARSER_ERROR[" + kn.getValue() + "]");
addStatus(new ErrorStatus("[" + kn.getValue() + "] is not a valid conversion word", this));
addToList(errConveter); // 记录当前node的Converter
}
}
}
return head;
}
CompositeConverter<E> createCompositeConverter(CompositeNode cn) {
String keyword = (String) cn.getValue();
// 只是从Map里取到Converter的类名,然后实例化
String converterClassStr = (String) converterMap.get(keyword);
if (converterClassStr != null) {
try {
// 实例化converter对象
return (CompositeConverter) OptionHelper.instantiateByClassName(converterClassStr, CompositeConverter.class, context);
} catch (Exception e) {
addError("Failed to instantiate converter class [" + converterClassStr + "] as a composite converter for keyword [" + keyword + "]", e);
return null;
}
} else {
addError("There is no conversion class registered for composite conversion word [" + keyword + "]");
return null;
}
}
DynamicConverter<E> createConverter(SimpleKeywordNode kn) {
String keyword = (String) kn.getValue();
// 只是从Map里取到Converter的类名,然后实例化
String converterClassStr = (String) converterMap.get(keyword);
if (converterClassStr != null) {
try {
return (DynamicConverter) OptionHelper.instantiateByClassName(converterClassStr, DynamicConverter.class, context);
} catch (Exception e) {
addError("Failed to instantiate converter class [" + converterClassStr + "] for keyword [" + keyword + "]", e);
return null;
}
} else {
addError("There is no conversion class registered for conversion word [" + keyword + "]");
return null;
}
}
3 架构一小步
3.1 pattern选择
logback提供了这么多关键字,在实际中也不可能都配上,到了生产环境有些也不太实用,比如上面用的%highlight,选择关键字的标准:
- 日志的主要目的是为了定位问题,所以应该选择一些对定位问题比较有帮助的。从日志看出问题后,最好是能够定位到代码的位置,也就是哪个类的哪个方法,甚至是哪一行代码。
- 打印日志不能影响业务的正常运行,比如打印日志不能消耗掉很多性能。
|-----------------------------|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------|
| 关键字 | 说明 | 备注 |
| %d{yyyy-MM-dd HH:mm:ss.SSS} | 打印日志的时间,要到毫秒 | |
| %-5level | 日志级别,主要有TRACE、DEBUG、INFO、WARN、ERROR,最多5个字符,为了对齐则定为最少5个字符 | |
| %thread | 线程标识,用于表示代码执行在哪个线程里 | |
| %logger{50} | logger名称,等同于节点的name属性。一般获取logger的时候使用的是含包名的类名,所以logger的名称实际上指的是包名+类名,可能很长,需要限制长度,比如50字符。也可以使用%class{50}来代替。 | 带包名的类名一般比较长,所以它和%class一般只用一个。用logger的好处是能兼容类名和一些特殊的logger名。 |
| %method | 方法名,打印代码所在的方法 | |
| %line | 行号,打印代码的行号位置 | 这个配置对定位问题是比较有用的,但其比较耗费性能,一般不配置,除非性能不是问题。 |
| %msg | 日志内容 | 最好在一个方法内能够唯一指示是哪个日志内容 |
| %n | 换行符 | |
示例:
java
Pattern=%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{50}#%method - %msg%n
202x-xx-xx xx:xx:xx.xxx DEBUG [http-nio-8080-exec-2] com.qqian.stepfmk.srvpro.hello.HelloController#say - Access saying hello, message=zhangsan
202x-xx-xx xx:xx:xx.xxx INFO [http-nio-8080-exec-2] com.qqian.stepfmk.srvpro.hello.HelloController#say - Access saying hello, message=zhangsan
202x-xx-xx xx:xx:xx.xxx WARN [http-nio-8080-exec-2] com.qqian.stepfmk.srvpro.hello.HelloController#say - Access saying hello, message=zhangsan
202x-xx-xx xx:xx:xx.xxx ERROR [http-nio-8080-exec-2] com.qqian.stepfmk.srvpro.hello.HelloController#say - Access saying hello, message=zhangsan
3.2 日志内容规范
相对于上面常用的信息,日志内容更加重要,但实际打印的时候,很多日志只是随意写了一句话,这句话大多是方法名的拼凑,这种日志只起到一个识别的作用,也就是帮助找到打印日志的位置,但是日志常用信息已经有此功能,所以这种日志除了知道代码有执行到这里之外,没有其它用,这就对定位问题几乎没有帮助。因此,有必要对日志内容定一些规范。
- 日志内容必要用一句简短的话说明日志出现的结果,这句话最好唯一。
- 强调结果是为了帮忙定位问题,而不是说明代码做了啥。代码做了啥是可以通过看代码了解到的。
- 实际日志一般打印不了行号,这句话若能够唯一,就能够快速定位到具体的代码,相当于有了代码行号。
- 比如判断一个中间变量为不合法l时打印日志,这句话应该说明该变量哪里不合法。通过这个说明就大致能够判断问题的所在,即使不能直接判断问题,也应该尽可能提供最多的信息量。
- 日志内容要包含上下文,没有上下文的日志不要打印。
- 上下文一般是指出现日志所指示结果的一些相关变量。
- 这些变量可能是从前面传过来的,也可能是中间产生的。
- 打印哪些变量衡量的标准是:当出现日志内容指示的结果时,需要哪些变量才能确定问题。比如一个从数据库读取数据的结果为null时,需要知道组装查询SQL的重点变量。
- 对于异常信息必须打印堆栈。
- 使用logger.error("xxxx", e)打印异常时,注意不要给e提供占位符,有占位符只打印了e.getMessage(),没有打印堆栈。
- 有堆栈才能详细看到是哪段代码发生异常,也就是帮助定位到具体的代码。