iOS学习笔记系列 - CocoaLumberjack

今天几乎花了一整天时间去看这个库，也算是有些心得，总结一下。

总纲
CocoaLumberjack项目架构
自定义日志分类
日志过滤及格式
文件日志

1. 总纲

CocoaLumberjack是个非常好用的开源日志库，做iOS的应该多多少少都有接触。可能有些人对这个名字不是很熟悉的，但代码上用的最多的日志命令DDLogInfo总还是见过的吧，它就是CocoaLumberjack提供的一个宏。

这篇文章主要看一下这个库的架构，和一些实际应用上的概念。为什么要看这些呢？原因有三：

了解除了平常的用DDLogInfo,DDLogError打一些日志之外，它还可以帮我们干什么；
如何去实现这些高级功能，比如配置自定义的日志框架，如何精确控制什么时候打什么日志，如何配置文件日志等等；
由于CocoaLumberjack是个开源项目，感兴趣的读者还可以在看完这篇文章之后去为开源社区贡献自己的一份力量。

2. CocoaLumberjack架构

总的来说，这个库由四个部分组成：DDLog, DDLogger, DDLogMessage, DDLogFormatter。我们逐个分析一下。

2.1 DDLog与DDLogger

如上图所示，DDLog是整个库的入口，我们平时用的DDLogLevel等宏就是直接调用DDLog的接口。一个DDLog包含着一个或多个DDLogger，比如常用的DDTTYLogger，DDASLLogger等等。当我们调用DDLogInfo的时候，DDLog会把已有的DDLogger全部遍历一遍，对于每个DDLogger都会调用其logMessage接口。当然细心的读者会意识到，这些操作不可能同步(SYNC)进行。而且如果要保证日志的相对顺序，必然会给DDLogger分配一个专属的线性队列(SERIAL_QUEUE)。详情可以参考笔者之前写的关于GCD的介绍。

2.2 DDLogger，DDLogFormatter与DDLogMessage

这三者之间的关系，用图像解释反而更加容易迷惑，还是用文字吧。

先阐述一下整个流程。DDLog调用DDLogger的时候，传入的是一个DDLogMessage实例。这个实例除了日志内容本身之外，还包含了关于这个日志的辅助信息，主要包括日志等级(level)，环境（context），队列（queueLabel），标签（tag），时间戳（timestamp）等等，他们的用法下面会有详细介绍。接着，DDLogger里面如果有DDLogFormatter的话，会先调用DDLogFormatter处理日志格式，对日志进行过滤等等操作，然后把日志打到Logger对应的位置。

这里要注意，每个DDLogger最多只能有一个DDLogFormatter实例，可以通过setLogFormatter：设置。但是，如果有需要同时应用多个DDLogFormatter的话，可以使用框架内置的一个DDMultiFormatter把需要用的整合到一起。这样就使得用户自定义formatter非常的方便。这里要注意两点：

DDMultiFormatter应用formatter时，是按照其添加的顺序逐个依次线性地进行的，所以往DDMultiFormatter上添加formatter时一定要注意添加的顺序；
虽然DDLogFormatter名字上叫做Formatter，它的功能并不局限于改变日志的格式。你还可以用它来过滤日志等等。

2.3 DDLogMessage相关属性

DDLogMessage属性的作用是给DDLogFormatter足够的信息去修改日志格式以及进行过滤筛选等操作。这里贴一下DDLogMessage的属性列表：

@interface DDLogMessage : NSObject 
{
    // Direct accessors to be used only for performance
    @public
    NSString *_message;
    DDLogLevel _level;
    DDLogFlag _flag;
    NSInteger _context;
    NSString *_file;
    NSString *_fileName;
    NSString *_function;
    NSUInteger _line;
    id _tag;
    DDLogMessageOptions _options;
    NSDate *_timestamp;
    NSString *_threadID;
    NSString *_threadName;
    NSString *_queueLabel;
}

大部分属性都相对比较容易理解，这里想着重梳理一下context和level。截止至写作日期，Github上的文档还没有更新，所以如果你去读文档的话，会感到非常混乱。CocoaLumberjack自从v2.x.x以来，社区大幅度地改变了对这两个属性的定义。

按照文档所说，用户可以通过在自己的头文件里#define自定义日志等级。但是如果你去试试就会发现根本行不通。原因是自从2.x版本以后，日志等级的定义方式由原来的宏改成了枚举(NS_ENUM)。这几乎杜绝了用户自定义日志等级。

3. 自定义日志分类

那么用户想在原有的几个等级上添加更详细的分类怎么办呢？没错，用 context。CocoaLumberjack默认context的值都是0. 如果你想添加新的分类，比如说DDLogNetwork，你需要做的就是定义自己的context 值。

#define LOG_CONTEXT_NETWORK 1

然后定义自己的宏：

#define DDLogNetworkInfo(frmt, ...)    LOG_MAYBE(LOG_ASYNC_ENABLED, LOG_LEVEL_DEF, DDLogFlagInfo,   LOG_CONTEXT_NETWORK, nil, __PRETTY_FUNCTION__, frmt, ##__VA_ARGS__)

这样的好处在于对日志等级和日志环境有了一个比较清晰的界定，也给了用户更多的自主权。比如说用户可以很方便地定义DDLogNetworkWarning和DDLogNetworkError, 等等。而不用像文档里面所说的先定义LOG_FLAG然后再用它来定义LOG_LEVEL之类复杂的操作。

4. 日志过滤及改变日志格式

按照上面所说的流程，日志过滤应该是DDLogFormatter的职责。没错，CocoaLumberjack自带了几个DDLogFormatter，包括DDContextWhitelistFilterLogFormatter, DDDispatchQueueLogFormatter等。前者可以通过设置context白名单过滤日志，适用于比如只想让当前Logger打某个环境值的日志。最常用的情况就是希望自定义一个新的分类，然后只把该分类的日志都打到一个文件里面。用法如下：

DDContextWhitelistFilterLogFormatter *contextFilter = [[DDContextWhitelistFilterLogFormatter alloc] init];
[contextFilter addToWhitelist: LOG_LEVEL_NETWORK];
[[DDTTYLogger sharedInstance] setLogFormatter:contextFilter];
[[DDLog addLogger:[DDTTYLogger sharedInstance] withLevel:DDLogLevelInfo];

这两个formatter只是个用法示例，用户完全可以根据自己的需要依样画葫芦，自定义格式化工具和过滤，然后加进指定的DDLogger。

5. 文件日志

CocoaLumberjack自带了一个文件日志类：DDFileLogger。如果不需要自定义日志路径的话，用法比较简单：

DDFileLogger *fileLogger = [[DDFileLogger alloc] init];
[DDLog addLogger:fileLogger withLevel:DDLogLevelInfo];

默认日志路径在：
/app/path/Library/Cached/。
如果需要自定义日志路径的话，需要稍微多几行代码：

NSString *path = "/Some/Path";
id logFileManager = [[DDLogFileManagerDefault alloc] initWithLogsDirectory:path];
logFileManager.maximumNumberOfLogFiles = 5; //可自行调整

DDFileLogger *fileLogger = [[DDFileLogger alloc] init];
fileLogger.rollingFrequency = 24*60*60; // 一天，可自行调整
[DDLog addLogger:fileLogger withLevel:DDLogLevelInfo];

写在最后

今天大概就先写到这里，希望能帮到有需要的人。如果有什么疑问欢迎在下面回复提出，笔者将尽量及时作出回复。