从零实现一个日志框架

亦凉 2023-09-28 14:53 119阅读 0赞

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 ###

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

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

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

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

![e9c5010f0a8034076f516b6899552e31.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

下面是一份最小配置的示例

除了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-/log

![83a0e4ffb04643c693e1535d07d97ab1.jpeg][]

[Link 1]: http://mp.weixin.qq.com/s?__biz=MzI4Njc5NjM1NQ==&mid=2247499172&idx=2&sn=e13096fca6076b9b7fef0a5ef71bbdae&chksm=ebd5c288dca24b9e5abf456837575ed7704fad7a9a76d7817378dbdd346106931fd00276f347&scene=21#wechat_redirect
[e9c5010f0a8034076f516b6899552e31.png]: https://img-blog.csdnimg.cn/img_convert/e9c5010f0a8034076f516b6899552e31.png
[83a0e4ffb04643c693e1535d07d97ab1.jpeg]: https://img-blog.csdnimg.cn/83a0e4ffb04643c693e1535d07d97ab1.jpeg