手把手教你从零设计一个日志框架


Java里的各种日志框架,相信大家都不陌生。Log4j/Log4j2/Logback/jboss logging等等,其实这些日志框架核心结构没什么区别,只是细节实现上和其性能上有所不同。本文带你从零开始,一步一步的设计一个日志框架。

输出内容 - LoggingEvent

提到日志框架,最容易想到的核心功能,那就是输出日志了。那么对于一行日志内容来说,应该至少包含以下几个信息:
  • 日志时间戳
  • 线程信息
  • 日志名称(一般是全类名)
  • 日志级别
  • 日志主体(需要输出的内容,比如info(str))


为了方便的管理输出内容,现在需要创建一个输出内容的类来封装这些信息:
public class LoggingEvent {
public long timestamp;//日志时间戳
private int level;//日志级别
private Object message;//日志主题
private String threadName;//线程名称
private long threadId;//线程id
private String loggerName;//日志名称

//getter and setters...

@Override
public String toString() {
    return "LoggingEvent{" +
            "timestamp=" + timestamp +
            ", level=" + level +
            ", message=" + message +
            ", threadName='" + threadName + '\'' +
            ", threadId=" + threadId +
            ", loggerName='" + loggerName + '\'' +
            '}';
}


对于每一次日志打印,应该属于一次输出的“事件-Event”,所以这里命名为LoggingEvent。

输出组件 - Appender

有了输出内容之后,现在需要考虑输出方式。输出的方式可以有很多:标准输出/控制台(Standard Output/Console)、文件(File)、邮件(Email)、甚至是消息队列(MQ)和数据库。

现在将输出功能抽象成一个组件“输出器” - Appender,这个Appender组件的核心功能就是输出,下面是Appender的实现代码:
public interface Appender {
void append(LoggingEvent event);


不同的输出方式,只需要实现Appender接口做不同的实现即可,比如ConsoleAppender - 输出至控制台。
public class ConsoleAppender implements Appender {
private OutputStream out = System.out;
private OutputStream out_err = System.err;

@Override
public void append(LoggingEvent event) {
    try {
        out.write(event.toString().getBytes(encoding));
    } catch (IOException e) {
        e.printStackTrace();
    }
}


日志级别设计 - Level

日志框架还应该提供日志级别的功能,程序在使用时可以打印不同级别的日志,还可以根据日志级别来调整那些日志可以显示,一般日志级别会定义为以下几种,级别从左到右排序,只有大于等于某级别的LoggingEvent才会进行输出。
ERROR > WARN > INFO > DEBUG > TRACE

现在来创建一个日志级别的枚举,只有两个属性,一个级别名称,一个级别数值(方便做比较)。
public enum Level {
ERROR(40000, "ERROR"), WARN(30000, "WARN"), INFO(20000, "INFO"), DEBUG(10000, "DEBUG"), TRACE(5000, "TRACE");

private int levelInt;
private String levelStr;

Level(int i, String s) {
    levelInt = i;
    levelStr = s;
}

public static Level parse(String level) {
    return valueOf(level.toUpperCase());
}

public int toInt() {
    return levelInt;
}

public String toString() {
    return levelStr;
}

public boolean isGreaterOrEqual(Level level) {
    return levelInt>=level.toInt();
}



日志级别定义完成之后,再将LoggingEvent中的日志级别替换为这个Level枚举。
public class LoggingEvent {
public long timestamp;//日志时间戳
private Level level;//替换后的日志级别
private Object message;//日志主题
private String threadName;//线程名称
private long threadId;//线程id
private String loggerName;//日志名称

//getter and setters...


现在基本的输出方式和输出内容都已经基本完成,下一步需要设计日志打印的入口,毕竟有入口才能打印嘛。

日志打印入口 - Logger

现在来考虑日志打印入口如何设计,作为一个日志打印的入口,需要包含以下核心功能:
  • 提供error/warn/info/debug/trace几个打印的方法
  • 拥有一个name属性,用于区分不同的Logger
  • 调用appender输出日志
  • 拥有自己的专属级别(比如自身级别为INFO,那么只有INFO/WARN/ERROR才可以输出)


先来简单创建一个Logger接口,方便扩展。
public interface Logger{
void trace(String msg);

void info(String msg);

void debug(String msg);

void warn(String msg);

void error(String msg);

String getName();


再创建一个默认的Logger实现类:
public class LogcLogger implements Logger{
private String name;
private Appender appender;
private Level level = Level.TRACE;//当前Logger的级别,默认最低
private int effectiveLevelInt;//冗余级别字段,方便使用

@Override
public void trace(String msg) {
    filterAndLog(Level.TRACE,msg);
}

@Override
public void info(String msg) {
    filterAndLog(Level.INFO,msg);
}

@Override
public void debug(String msg) {
    filterAndLog(Level.DEBUG,msg);
}

@Override
public void warn(String msg) {
    filterAndLog(Level.WARN,msg);
}

@Override
public void error(String msg) {
    filterAndLog(Level.ERROR,msg);
}

/**
 * 过滤并输出,所有的输出方法都会调用此方法
 * @param level 日志级别
 * @param msg 输出内容
 */
private void filterAndLog(Level level,String msg){
    LoggingEvent e = new LoggingEvent(level, msg,getName());
    //目标的日志级别大于当前级别才可以输出
    if(level.toInt() >= effectiveLevelInt){
        appender.append(e);
    }
}

@Override
public String getName() {
    return name;
}

//getters and setters...


好了,到现在为止,现在已经完成了一个最最最基本的日志模型,可以创建Logger,输出不同级别的日志。不过显然还不太够,还是缺少一些核心功能。

日志层级 - Hierarchy

一般在使用日志框架时,有一个很基本的需求:不同包名的日志使用不同的输出方式,或者不同包名下类的日志使用不同的日志级别,比如我想让框架相关的DEBUG日志输出,便于调试,其他默认用INFO级别。

而且在使用时并不希望每次创建Logger都引用一个Appender,这样也太不友好了;最好是直接使用一个全局的Logger配置,同时还支持特殊配置的Logger,且这个配置需要让程序中创建Logger时无感(比如LoggerFactory.getLogger(XXX.class))。

可上面现有的设计可无法满足这个需求,需要稍加改造。

现在设计一个层级结构,每一个Logger拥有一个Parent Logger,在filterAndLog时优先使用自己的Appender,如果自己没有Appender,那么就向上调用父类的appnder,有点反向“双亲委派(parents delegate)”的意思。
1.png

上图中的Root Logger,就是全局默认的Logger,默认情况下它是所有Logger(新创建的)的Parent Logger。所以在filterAndLog时,默认都会使用Root Logger的appender和level来进行输出。

现在将filterAndLog方法调整一下,增加向上调用的逻辑:
private LogcLogger parent;//先给增加一个parent属性

private void filterAndLog(Level level,String msg){
LoggingEvent e = new LoggingEvent(level, msg,getName());
//循环向上查找可用的logger进行输出
for (LogcLogger l = this;l != null;l = l.parent){
    if(l.appender == null){
        continue;
    }
    if(level.toInt()>effectiveLevelInt){
        l.appender.append(e);
    }
    break;
}


好了,现在这个日志层级的设计已经完成了,不过上面提到不同包名使用不同的Logger配置,还没有做到,包名和Logger如何实现对应呢?

其实很简单,只需要为每个包名的配置单独定义一个全局Logger,在解析包名配置时直接为不同的包名。

日志上下文 - LoggerContext

考虑到有一些全局的Logger,和Root Logger需要被各种Logger引用,所以得设计一个Logger容器,用来存储这些Logger。
/**
* 一个全局的上下文对象
*/
public class LoggerContext {

/**
 * 根logger
 */
private Logger root;

/**
 * Logger缓存,存放解析配置文件后生成的Logger对象,以及通过程序手动创建的Logger对象
 */
private Map<String,Logger> loggerCache = new HashMap<>();

public void addLogger(String name,Logger logger){
    loggerCache.put(name,logger);
}

public void addLogger(Logger logger){
    loggerCache.put(logger.getName(),logger);
}
//getters and setters...


有了存放Logger对象们的容器,下一步可以考虑创建Logger了。

日志创建 - LoggerFactory

为了方便的构建Logger的层级结构,每次new可不太友好,现在创建一个LoggerFactory接口。
public interface ILoggerFactory {
//通过class获取/创建logger
Logger getLogger(Class<?> clazz);
//通过name获取/创建logger
Logger getLogger(String name);
//通过name创建logger
Logger newLogger(String name);


再来一个默认的实现类:
public class StaticLoggerFactory implements ILoggerFactory {

private LoggerContext loggerContext;//引用LoggerContext

@Override
public Logger getLogger(Class<?> clazz) {
    return getLogger(clazz.getName());
}

@Override
public Logger getLogger(String name) {
    Logger logger = loggerContext.getLoggerCache().get(name);
    if(logger == null){
        logger = newLogger(name);
    }
    return logger;
}

/**
 * 创建Logger对象
 * 匹配logger name,拆分类名后和已创建(包括配置的)的Logger进行匹配
 * 比如当前name为com.aaa.bbb.ccc.XXService,那么name为com/com.aaa/com.aaa.bbb/com.aaa.bbb.ccc
 * 的logger都可以作为parent logger,不过这里需要顺序拆分,优先匹配“最近的”
 * 在这个例子里就会优先匹配com.aaa.bbb.ccc这个Logger,作为自己的parent
 *
 * 如果没有任何一个Logger匹配,那么就使用root logger作为自己的parent
 *
 * @param name Logger name
 */
@Override
public Logger newLogger(String name) {
    LogcLogger logger = new LogcLogger();
    logger.setName(name);
    Logger parent = null;
    //拆分包名,向上查找parent logger
    for (int i = name.lastIndexOf("."); i >= 0; i = name.lastIndexOf(".",i-1)) {
        String parentName = name.substring(0,i);
        parent = loggerContext.getLoggerCache().get(parentName);
        if(parent != null){
            break;
        }
    }
    if(parent == null){
        parent = loggerContext.getRoot();
    }
    logger.setParent(parent);
    logger.setLoggerContext(loggerContext);
    return logger;
}


再来一个静态工厂类,方便使用:
public class LoggerFactory {

private static ILoggerFactory loggerFactory = new StaticLoggerFactory();

public static ILoggerFactory getLoggerFactory(){
    return loggerFactory;
}

public static Logger getLogger(Class<?> clazz){
    return getLoggerFactory().getLogger(clazz);
}

public static Logger getLogger(String name){
    return getLoggerFactory().getLogger(name);
}


至此,所有基本组件已经完成,剩下的就是装配了。

配置文件设计

配置文件需至少需要有以下几个配置功能:
  • 配置Appender
  • 配置Logger
  • 配置Root Logger


下面是一份最小配置的示例。
<configuration>

<appender name="std_plain" class="cc.leevi.common.logc.appender.ConsoleAppender">
</appender>

<logger name="cc.leevi.common.logc">
    <appender-ref ref="std_plain"/>
</logger>

<root level="trace">
    <appender-ref ref="std_pattern"/>
</root>
</configuration>

除了XML配置,还可以考虑增加YAML/Properties等形式的配置文件,所以这里需要将解析配置文件的功能抽象一下,设计一个Configurator接口,用于解析配置文件:
public interface Configurator {
void doConfigure();


再创建一个默认的XML形式的配置解析器:
public class XMLConfigurator implements Configurator{

private final LoggerContext loggerContext;

public XMLConfigurator(URL url, LoggerContext loggerContext) {
    this.url = url;//文件url
    this.loggerContext = loggerContext;
}

@Override
public void doConfigure() {
    try{
        DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
        DocumentBuilder documentBuilder = factory.newDocumentBuilder();
        Document document = documentBuilder.parse(url.openStream());
        parse(document.getDocumentElement());
        ...
    }catch (Exception e){
        ...
    }
}
private void parse(Element document) throws IllegalAccessException, ClassNotFoundException, InstantiationException {
    //do parse...
}


解析时,装配LoggerContext,将配置中的Logger/Root Logger/Appender等信息构建完成,填充至传入的LoggerContext。

现在还需要一个初始化的入口,用于加载/解析配置文件,提供加载/解析后的全局LoggerContext。
public class ContextInitializer {
final public static String AUTOCONFIG_FILE = "logc.xml";//默认使用xml配置文件
final public static String YAML_FILE = "logc.yml";

private static final LoggerContext DEFAULT_LOGGER_CONTEXT = new LoggerContext();

/**
* 初始化上下文
*/
public static void autoconfig() {
    URL url = getConfigURL();
    if(url == null){
        System.err.println("config[logc.xml or logc.yml] file not found!");
        return ;
    }
    String urlString = url.toString();
    Configurator configurator = null;

    if(urlString.endsWith("xml")){
        configurator = new XMLConfigurator(url,DEFAULT_LOGGER_CONTEXT);
    }
    if(urlString.endsWith("yml")){
        configurator = new YAMLConfigurator(url,DEFAULT_LOGGER_CONTEXT);
    }
    configurator.doConfigure();
}

private static URL getConfigURL(){
    URL url = null;
    ClassLoader classLoader = ContextInitializer.class.getClassLoader();
    url = classLoader.getResource(AUTOCONFIG_FILE);
    if(url != null){
        return url;
    }
    url = classLoader.getResource(YAML_FILE);
    if(url != null){
        return url;
    }
    return null;
}

/**
*  获取全局默认的LoggerContext
*/
public static LoggerContext getDefautLoggerContext(){
    return DEFAULT_LOGGER_CONTEXT;
}


现在还差一步,将加载配置文件的方法嵌入LoggerFactory,让LoggerFactory.getLogger的时候自动初始化,来改造一下StaticLoggerFactory:
public class StaticLoggerFactory implements ILoggerFactory {

private LoggerContext loggerContext;

public StaticLoggerFactory() {
    //构造StaticLoggerFactory时,直接调用配置解析的方法,并获取loggerContext
    ContextInitializer.autoconfig();
    loggerContext = ContextInitializer.getDefautLoggerContext();
}


现在,一个日志框架就已经基本完成了。虽然还有很多细节没有完善,但主体功能都已经包含,麻雀虽小五脏俱全。

完整代码

本文中为了便于阅读,有些代码并没有贴上来,详细完整的代码可以参考:https://github.com/kongwu-/logc

原文链接:https://segmentfault.com/a/1190000038760707

0 个评论

要回复文章请先登录注册