当前位置: > > > Swift - 日志框架XCGLogger的使用详解

Swift - 日志框架XCGLogger的使用详解

前面我写过两篇文章演示如何封装一个日志函数,实现日志的格式化输出,以及日志文件的保存。
Swift - 实现日志输出的封装1(显示出调用的文件名、方法、行号)
Swift - 实现日志输出的封装2(同步记录到文件中去)
除了自己实现外,网上还有许多功能更加强大的第三方日志框架供我们使用。本文介绍其中一个比较优秀的日志框架:XCGLogger

一、XCGLogger的介绍与配置

1,什么是XCGLogger

  • XCGLogger 是一个 debug 日志框架,可用于 Swift 项目中。
  • 使用 XCGLogger ,除了可以将日志详细信息输出到控制器台外,还可以输出到指定的文件中去。
  • 虽然使用起来同 NSLog() print() 差不多,但 XCGLogger 会附带更多的额外信息,比如:日期、函数名、文件名和行号。
比如我们可以使用 XCGLogger 输出如下这种最简单的日志信息:

也可以通过配置,输出下面这种完整的日志信息:


2,XCGLogger的安装与配置

(1)从 GitHub 上下载最新的代码:https://github.com/DaveWoodCom/XCGLogger
(2)将下载下来的源码包中 XCGLogger.xcodeproj 拖拽至你的工程中

(3)工程 -> General -> Embedded Binaries 项,把 iOS 版的 framework 添加进来:XCGLogger.framework 

(4)最后,在需要使用 XCGLogger 的地方 import 进来就可以了
import XCGLogger

二、基本用法

1,XCGLogger初始化

(1)我们可以在 AppDelegate.swift 中定义一个全局的日志对象,方便使用。
(2)同时对这个日志对象进行初始化。
  • 这里我选择打印所有的日志信息(级别、方法名、文件名、行号)。
  • 日志除了会打印在控制台中外,还会同步输出到文件中(Library/Caches/log.txt)。
  • 同时日志在控制台打印和文件输出的消息级别一样,都是 debug 级。
import UIKit
import XCGLogger

let log = XCGLogger.default

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions
        launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        
        //日志文件地址
        let cachePath = FileManager.default.urls(for: .cachesDirectory,
                                                 in: .userDomainMask)[0]
        let logURL = cachePath.appendingPathComponent("log.txt")

        //日志对象设置
        log.setup(level: .debug, showThreadName: true, showLevel: true,
                  showFileNames: true, showLineNumbers: true,
                  writeToFile: logURL, fileLevel: .debug)
        
        return true
    }

    func applicationWillResignActive(_ application: UIApplication) {
    }

    func applicationDidEnterBackground(_ application: UIApplication) {
    }

    func applicationWillEnterForeground(_ application: UIApplication) {
    }

    func applicationDidBecomeActive(_ application: UIApplication) {
    }

    func applicationWillTerminate(_ application: UIApplication) {
    }
}

2,日志输出

通过 XCGLogger 内置的方法,我们可以输出各种消息级别的日志信息。比如下面样例我们打印从低到高各种级别的日志。
import UIKit

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        
        log.verbose("一条verbose级别消息:程序执行时最详细的信息。")
        log.debug("一条debug级别消息:用于代码调试。")
        log.info("一条info级别消息:常用与用户在console.app中查看。")
        log.warning("一条warning级别消息:警告消息,表示一个可能的错误。")
        log.error("一条error级别消息:表示产生了一个可恢复的错误,用于告知发生了什么事情。")
        log.severe("一条severe error级别消息:表示产生了一个严重错误。程序可能很快会奔溃。")
    }
    
    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
    }
}

3,运行效果

控制台输出如下。可以看到由于我们前面将日志显示级别设置成 debug,所以 verbose 级别的日志消息就不会打印。 

三、更高级的初始化方法

通常情况下我们只需要像上面样例一样,使用 setup 方法初始化 XCGLogger 对象相关配置即可。方便简单,代码也少。
当然 XCGLogger 也支持更加灵活的配置,使得我们日志记录会更加可控。比如:想让控制台显示的信息与日志文件里记录的信息不一样。
//创建一个logger对象
let log = XCGLogger(identifier: "advancedLogger", includeDefaultDestinations: false)

//控制台输出
let systemDestination = AppleSystemLogDestination(identifier: "advancedLogger.systemDestination")

//设置控制台输出的各个配置项
systemDestination.outputLevel = .debug
systemDestination.showLogIdentifier = false
systemDestination.showFunctionName = true
systemDestination.showThreadName = true
systemDestination.showLevel = true
systemDestination.showFileName = true
systemDestination.showLineNumber = true
systemDestination.showDate = true

//logger对象中添加控制台输出
log.add(destination: systemDestination)

//日志文件地址
let cachePath = FileManager.default.urls(for: .cachesDirectory,
                                         in: .userDomainMask)[0]
let logURL = cachePath.appendingPathComponent("log.txt")
//文件出输出
let fileDestination = FileDestination(writeToFile: logURL,
                                      identifier: "advancedLogger.fileDestination")

//设置文件输出的各个配置项
fileDestination.outputLevel = .debug
fileDestination.showLogIdentifier = false
fileDestination.showFunctionName = true
fileDestination.showThreadName = true
fileDestination.showLevel = true
fileDestination.showFileName = true
fileDestination.showLineNumber = true
fileDestination.showDate = true

//文件输出在后台处理
fileDestination.logQueue = XCGLogger.logQueue

//logger对象中添加控制台输出
log.add(destination: fileDestination)

//开始启用
log.logAppDetails()

四、过滤日志信息

1,按文件名过滤

(1)下面代码不显示 AppDelegate.swift 中输出的日志,其它文件日志都会显示
log.filters = [FileNameFilter(excludeFrom: ["AppDelegate.swift"],
                              excludePathWhenMatching: true)]

(2)下面代码只显示 AppDelegate.swift 中输出的日志,其它文件日志都不显示
log.filters = [FileNameFilter(includeFrom: ["AppDelegate.swift"],
                              excludePathWhenMatching: true)]

2,按标签过滤

(1)使用自定义的标签字符串。
比如我们在输出一条 debug 消息时,附上一个自定义的标签(sensitive
let tags = XCGLogger.Constants.userInfoKeyTags
log.debug("这里进行用户身份验证。",userInfo: [tags: "sensitive"])
下面设置分别是不显示这个标签的日志,以及只显示这个标签的日志。
//下面代码不显示标签为“sensitive”的日志,其它日志都会显示
log.filters = [TagFilter(excludeFrom: ["sensitive"])]

//下面代码只显示标签为“sensitive”的日志,其它日志都不会显示
log.filters = [TagFilter(includeFrom: ["sensitive"])]

(2)通过扩展 Tag Dev 这两个标签结构体
Tag Dev XCGLogger 自带的,我们这里通过扩展,在其上面添加一个些自定义标签。
extension Tag {
    static let sensitive = Tag("sensitive")
    static let ui = Tag("ui")
    static let data = Tag("data")
}

extension Dev {
    static let dave = Dev("dave")
    static let sabby = Dev("sabby")
}
我们日志输出时可以混合使用多个标签:
//设置多个标签
log.debug("A tagged log message", userInfo: Dev.dave | Tag.sensitive)

//设置单个标签
log.debug("Another tagged log message", userInfo: Dev.dave.dictionary)
下面根据便签进行日志过滤:
//下面代码不显示标签只为“dave”或“sensitive”的日志,其它日志都会显示
log.filters = [TagFilter(excludeFrom: [Dev.dave, Tag.sensitive])]

//下面代码只显示标签为“dave”或“sensitive”的日志,其它日志都不会显示
log.filters = [TagFilter(includeFrom: [Dev.dave, Tag.sensitive])]

五、选择性的执行代码

有时我们日志输出前要进行一些计算或操作,再将结果通过日志打印出来。由于这些操作与程序实际运行无关,只是用于日志打印,那么我们可以将其放置在日志方法闭包中。这样既保证代码的干净,同时如果日志不输出的话也不会浪费系统资源。
比如下面样例,如果我们将日志消息级别调到 debug 以上,那么下面日志不会输出,且内部的循环操作自然也不会执行。
log.debug {
    var total = 0.0
    for receipt in receipts {
        total += receipt.total
    }
    
    return "Total of all receipts: \(total)"
}

六、日期格式化

默认日志输出的格式是“2016-12-15 20:06:27.923”这种形式。当然我们也可以改成任意的自定义的格式。
let dateFormatter = DateFormatter()
dateFormatter.dateFormat = "MM/dd/yyyy hh:mma"
dateFormatter.locale = Locale.current
log.dateFormatter = dateFormatter

七、自动切换配置

通过使用 Swift 的编译标志(build flags),我们可以在程序调试、生产版本中自动使用不同的日志级别和日志条目。
#if DEBUG
log.setup(level: .debug, showThreadName: true, showLevel: true,
          showFileNames: true, showLineNumbers: true)
#else
log.setup(level: .severe, showThreadName: true, showLevel: true,
          showFileNames: true, showLineNumbers: true)
#endif

八、在后台进行日志处理

默认情况下,日志输出是在调用它们的进程里进行的。这样可以确保日志消息可以立刻显示,方便我们使用断点调试时可以立刻看到结果。
但在发布的生产版本中,如果日志也在当前线程中执行会对性能造成一些影响。我们可以指定日志目标进程使用哪个执行队列中。

1,下面两种方法都是实现将日志文件输出放在后台线程中进行:

//方式1
fileDestination.logQueue = XCGLogger.logQueue

//方式2
fileDestination.logQueue = DispatchQueue.global(qos: .background)

2,也可以通过build flags来实现程序在调试、生产自动使用不同线程

#if DEBUG
    log.setup(level: .debug, showThreadName: true, showLevel: true,
              showFileNames: true, showLineNumbers: true)
#else
    log.setup(level: .severe, showThreadName: true, showLevel: true,
              showFileNames: true, showLineNumbers: true)
    if let consoleLog = log.logDestination(XCGLogger.Constants.baseConsoleDestinationIdentifier)
        as? ConsoleDestination {
        consoleLog.logQueue = XCGLogger.logQueue
    }
#endif

九、实现日志文件的增量记录

默认情况下,日志文件的输出的是覆盖模式的。也就是说,我们指定了一个日志文件路径,程序每次重新启动时,如果这个文件原来就存在,其内容也会被覆盖。
  • 我们可以在日志配置时将 shouldAppend 参数设置为 true,这样如果原来的文件存在,也不会重新覆盖。而是将新日志信息添加到文件尾部。
  • 同时 appendMarker 可以设置个字符串,其在每次程序启动时会自动添加到日志文件中。方便我们区分开每次程序运行的日志。
//创建一个logger对象
let log = XCGLogger(identifier: "advancedLogger", includeDefaultDestinations: false)

//控制台输出
let systemDestination = AppleSystemLogDestination(identifier: "advancedLogger.systemDestination")

//设置各个配置项
systemDestination.outputLevel = .debug
systemDestination.showLogIdentifier = false
systemDestination.showFunctionName = true
systemDestination.showThreadName = true
systemDestination.showLevel = true
systemDestination.showFileName = true
systemDestination.showLineNumber = true
systemDestination.showDate = true

//logger对象中添加控制台输出
log.add(destination: systemDestination)

//日志文件地址
let cachePath = FileManager.default.urls(for: .cachesDirectory,
                                         in: .userDomainMask)[0]
let logURL = cachePath.appendingPathComponent("log.txt")
//文件出输出
let fileDestination = FileDestination(writeToFile: logURL,
                                      identifier: "advancedLogger.fileDestination",
                                      shouldAppend: true, appendMarker: "-- Relauched App --")

//设置各个配置项
fileDestination.outputLevel = .debug
fileDestination.showLogIdentifier = false
fileDestination.showFunctionName = true
fileDestination.showThreadName = true
fileDestination.showLevel = true
fileDestination.showFileName = true
fileDestination.showLineNumber = true
fileDestination.showDate = true

//文件输出在后台处理
fileDestination.logQueue = XCGLogger.logQueue

//logger对象中添加控制台输出
log.add(destination: fileDestination)

//开始启用
log.logAppDetails()

比如我们这里一共启动了三次应用,日志文件的内容如下:

十,实现日志文件的转储

上面的样例中,我们都是将日志记录到 Caches 文件夹下的 log.txt。如果是增量日志的话,那个这个文件就会越来越大。所以我们可以通过 rotateFile(to:) 方法实现日志的转储。比如:每隔一段时间,或每当日志文件到一定大小时调用下该方法,将日志内容转储到另一个文件中。(注意:转储后原来日志文件里的内容会清空。)
具体转储操作的步骤如下:
  • 首先通过 XCGLogger destination(withIdentifier:) 方法获取 FileDestination 对象。
  • 再调用 FileDestination 对象的 rotateFile(to:) 方法将日志文件转储到指定路径。
  • rotateFile(to:) 方法执行成功后会返回 true。根据结果我们可以进行一些后续操作。比如:压缩、邮件发送日志文件等等。
下面代码我们将日志文件转储到用户文档目录下:
//获取FileDestination
let fileDestination = log.destination(withIdentifier: "advancedLogger.fileDestination")
    as! FileDestination

//获取用户文档目录
let documentPath = FileManager.default.urls(for: .documentDirectory,
                                         in: .userDomainMask)[0]
let logURL = documentPath.appendingPathComponent("log.txt")

//将当前的日志文件复制到用户文档目录中去
fileDestination.rotateFile(to: logURL)

如果觉得我的文章对您有用,请随意打赏。您的支持将鼓励我继续创作。

打赏支持
评论0