QuantiLogger

QuantiLogger 是一个超轻量级的 iOS 开发 Swift 日志库。它提供了一些预构建的日志记录器，包括原生的 os_log 或文件日志记录器。它还提供了一个接口来创建自定义日志记录器。

需求

• Swift 5.0+
• Xcode 10+
• iOS 11.0+
• RxSwift 4.0+（注意：QuantiLogger 使用 RxSwift 库集，并利用其提供的响应式功能。）

安装

Carthage

Carthage 是一个去中心化的依赖关系管理器，它会构建您的依赖关系并为您提供二进制框架。您可以使用以下命令通过 Homebrew 安装 Carthage

$ brew update
$ brew install carthage

为了使用 Carthage 将 QuantiLogger 集成到您的 Xcode 项目中，请在您的 Cartfile 中指定它

github "Qase/QuantiLogger" ~> 1.17

运行 carthage update 命令来构建框架，并将构建好的 QuantiLogger.framework 及其依赖项拖入您的 Xcode 项目中。

CocoaPods

CocoaPods 是 Cocoa 项目的依赖管理器。您可以使用以下命令安装它：

$ gem install cocoapods

要使用 CocoaPods 将 QuantiLogger 集成到您的 Xcode 项目中，请在 Podfile 中指定它。

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '11.0'
use_frameworks!

target '<Your Target Name>' do
  pod 'QuantiLogger', '~> 1.17'
end

然后，运行以下命令：

$ pod install

使用方法

日志级别

可以在不同的级别进行日志记录。每个可以支持不同级别的记录器，这意味着它只记录这样的日志消息。例如，可以设置多个相同类型的记录器，以支持不同的级别，从而在不同的级别上进行日志分离。另一个用例是进一步筛选由其级别声明的特定类型的消息。

虽然开发者肯定可以选择如何使用这些级别，但由于每个级别都具有不同的用途，因此仍有推荐的使用方式。

• 使用 info 记录与 UI 相关的用户操作
• 使用 debug 进行调试
• 使用 verbose 进行扩展调试，尤其是在需要非常具体的消息时
• 使用 warn 记录警告
• 使用 error 记录错误
• 使用 system（仅限 native os_log）匹配 os_log_fault -> 向日志系统发送故障级别的消息
• 使用 process（仅限 native os_log）匹配 os_log_error -> 向日志系统发送错误级别的消息

预构建记录器

ConsoleLogger

最简单的记录器。封装了 Swift 标准库中的 print(_:separator:terminator:) 函数。

SystemLogger

封装原生OSLog，用于系统级别记录消息。

FileLogger

允许将日志记录到文件中。每个日志文件对应一天的数据。另一天，将使用另一个日志文件。使用numberOfLogFiles指定保存的日志文件数量。换句话说，应该保留多少天（日志文件）。如果最后的日志文件满了，第一个将使用最简单的循环策略覆盖。

WebLogger

通过REST API将日志记录到目标服务器。为了减少流量，发送时将日志分组到所谓的批次中。用户可以设置批次的大小以及发送单独批次之间的时间间隔。

以下是一个日志批次的JSON示例

[{"severity": "VERBOSE",
  "sessionName": "E598B4C1-2B08-4563-81C0-2A77E5CE0C3C",
  "message":"/some/path/QuantiLoggerTests.swift - testWebLogger() - line 165: Test verbose",
  "timestamp": 1529668897.318845},
 {"severity": "INFO",
  "sessionName":"E598B4C1-2B08-4563-81C0-2A77E5CE0C3C",
  "message": "/some/path/QuantiLoggerTests.swift - testWebLogger() - line 166: Test system",
  "timestamp":1529668897.3196549},
 {"severity":"INFO",
  "sessionName":"E598B4C1-2B08-4563-81C0-2A77E5CE0C3C",
  "message":"/some/path/QuantiLoggerTests.swift - testWebLogger() - line 167: Test process",
  "timestamp":1529668897.3196959
}]

以下是一组用户可以自定义的属性

• serverUrl 目标服务器的URL
• sessionName 要登录的会话名称
• sizeOfBatch 日志批次的大小
• timeSpan 发送单独批次之间的时间间隔

接收日志的目标服务器独立于WebLogger。因此，用户可以实现一个自定义服务器，以某种喜爱的方式显示日志。如果不希望实现自定义服务器，我们还提供了用Node.js编写的简单服务器解决方案。

ApplicationCallbackLogger

一种特殊的日志器，可以自动记录所有接收到的UIApplication通知，之后称为应用程序回调。以下是支持的应用程序回调完整列表

• UIApplicationWillTerminate
• UIApplicationDidBecomeActive
• UIApplicationWillResignActive
• UIApplicationDidEnterBackground
• UIApplicationDidFinishLaunching
• UIApplicationWillEnterForeground
• UIApplicationSignificantTimeChange
• UIApplicationUserDidTakeScreenshot
• UIApplicationDidChangeStatusBarFrame
• UIApplicationDidReceiveMemoryWarning
• UIApplicationWillChangeStatusBarFrame
• UIApplicationDidChangeStatusBarOrientation
• UIApplicationWillChangeStatusBarOrientation
• UIApplicationProtectedDataDidBecomeAvailable
• UIApplicationBackgroundRefreshStatusDidChange
• UIApplicationProtectedDataWillBecomeUnavailable

记录器已集成并自动设置，因此它按照原样记录所有应用回调的debug级别的日志。通过在LogManager上使用setApplicationCallbackLogger(with: [ApplicationCallbackType]?)，用户可以指定需要记录的应用回调（默认情况下都会记录所有回调）。如果传入空数组，所有应用回调都将被记录。如果传入nil，则不会记录任何应用回调。通过使用setApplicationCallbackLogger(onLevel: Level)，用户可以设置特定的日志级别来记录应用回调（默认使用debug级别）。通过使用setApplicationCallbackLogger(with: [ApplicationCallbackType]?, onLevel: Level)，用户可以同时设置应用回调和级别。

MetaInformationLogger

一种特殊的记录器，能够记录关于应用程序和宿主应用的各种元信息。以下是支持的所有元信息的完整列表

• identifier 应用唯一标识符
• compiler 使用的编译器版本
• version CFBundleShortVersionString，即应用程序的版本
• buildNumber CFBundleVersion，即应用程序的构建号
• modelType 宿主设备的模型
• currentOSVersion 宿主设备的当前OS版本
• upTime 应用的启动时间
• language 宿主设备的本地化

记录器通过在LogManager上使用logMetaInformation(_: [MetaInformationType])方法在框架外部可访问。它允许明确列出应记录的元信息。如果不明确指定，则记录所有元信息。

创建自定义记录器

只需实现Logging协议即可创建自定义记录器。在 simplest 形式下，自定义记录器只需实现log(_:onLevel:)和levels()方法。可选地，它还可以实现configure()方法，如有必要在开始记录之前进行配置。

以下是一个自定义记录器的示例，它允许记录到Crashlytics

import Fabric
import Crashlytics

class CrashLyticsLogger: QuantiLogger.Logging {
    open func configure() {
        Fabric.with([Crashlytics.self])
    }
    
    open func log(_ message: String, onLevel level: Level) {
        CLSLogv("%@", getVaList(["[\(level.rawValue) \(Date().toFullDateTimeString())] \(message)"]))
    }

    open func levels() -> [Level] {
        return [.verbose, .info, .debug, .warn, .error]
    }

}

初始化

通过LogManager Singleton 实例执行日志初始化。LogManager 托管着所有配置的记录器，并管理着日志记录。

以下是如何使用 FileLogger、ConsoleLogger 和之前创建的自定义 CrashLyticsLogger 来初始化日志记录器的示例。

let logManager = LogManager.shared

let fileLogger = FileLogger()
fileLogger.levels = [.warn, .error]
logManager.add(fileLogger)

let systemLogger = ConsoleLogger()
systemLogger.levels = [.verbose, .info, .debug, .warn, .error]
logManager.add(systemLogger)

let crashlyticsLogger = CrashLyticsLogger()
logManager.add(crashlyticsLogger)

日志记录

日志记录是通过简单的 QLog(_:onLevel) 宏函数完成的。此类函数可以在引入了 QuantiLogger 的任何地方使用。

如何记录日志的示例

QLog("This is the message to be logged.", onLevel: .info)

并发模式

QuantiLogger 目前支持 3 种不同的并发模式。模式是通过设置 LogManager 的 loggingConcurrencyMode 属性来设置的。默认值为 asyncSerial。

syncSerial

日志任务在自定义串行队列上同步派遣，其中所有日志记录器逐个按顺序执行其任务。

asyncSerial

日志任务在自定义串行队列上异步派遣，其中所有日志记录器逐个按顺序执行其任务。

syncConcurrent

日志任务在自定义串行队列上同步派遣，其中所有日志记录器并发执行其任务。

通过邮件发送文件日志

框架还提供了一个名为LogFilesViaMailViewController的控制器，它包含一个预配置的控制器，当显示时，将提供发送所有日志文件的选项。它使用init(withRecipients:)方法构建，其中withRecipients是一个包含所有邮件收件人的[String]数组。

一个示例可以被看到在QuantiLoggerExample中的SendLogFilesViaMailViewController形式，这是框架中的一个工作示例（克隆项目以查看）。

在UITableView中显示文件日志

框架还提供了一个名为FileLoggerTableViewDatasource的预配置的UITableViewDataSource，它包含所有合并的日志文件，每个日志对应一个UITableViewCell。

可以在QuantiLoggerExample中的LogListTableViewController形式找到示例，这是框架中的一个工作示例（克隆项目以查看）。

许可证

QuantiLogger遵循发布。