XCGLogger - Swift项目的高级日志框架简化调试和错误追踪

![XCGLogger][xcglogger-logo]

[![badge-language]][swift.org] [![badge-platforms]][swift.org] [![badge-license]][license]

[![badge-swiftpm]][swiftpm] [![badge-cocoapods]][cocoapods-xcglogger] [![badge-carthage]][carthage]

[][mastodon-davewoodx] [][twitter-davewoodx]

[][cerebral-gardens] [][patreon-davewoodx]

简而言之

XCGLogger是Swift项目中使用的原始调试日志模块。

由于Swift不包含C预处理器,开发者无法使用他们在Objective-C中使用的调试日志#define宏。这意味着我们传统的生成漂亮调试日志的方式不再有效。仅仅使用普通的print调用会丢失很多有用的信息,或者需要你输入更多的代码。

XCGLogger允许你将详细信息记录到控制台(也可以选择记录到文件或其他自定义目的地),就像你使用NSLog()或print()一样,但包含额外的信息,如日期、函数名、文件名和行号。

从这样:

简单消息

变成这样:

2014-06-09 06:44:43.600 [Debug] [AppDelegate.swift:40] application(_:didFinishLaunchingWithOptions:): 简单消息

示例

交流 (致谢 AlamoFire)

如果你需要帮助,请使用[Stack Overflow]stackoverflow。
如果你想问一个一般性问题,请使用[Stack Overflow][stackoverflow]。
如果你发现了一个bug,请提交issue。
如果你有功能请求,请提交issue。
如果你想贡献代码,请提交pull request。
如果你使用XCGLogger,请在[GitHub][github-xcglogger]上给项目加星。

安装

Git子模块

在你的仓库文件夹中执行:

git submodule add https://github.com/DaveWoodCom/XCGLogger.git

[Carthage][carthage]

在你的Cartfile中添加以下行。

github "DaveWoodCom/XCGLogger" ~> 7.1.5

然后运行carthage update --no-use-binaries或者只运行carthage update。有关Carthage的安装和使用详情,请访问[其项目页面][carthage]。

使用Swift 5.0及以上版本的开发者需要在Copy Carthage Frameworks构建阶段的Input Files中添加$(SRCROOT)/Carthage/Build/iOS/ObjcExceptionBridging.framework。

[CocoaPods][cocoapods]

在你的Podfile中添加类似以下几行。你可能需要根据你的平台、版本/分支等进行调整。

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

pod 'XCGLogger', '~> 7.1.5'

单独指定pod XCGLogger将包含核心框架。我们正在开始添加子规范,允许你也包含可选组件:

pod 'XCGLogger/UserInfoHelpers', '~> 7.1.5': 包含一些实验性代码,帮助处理使用UserInfo字典来标记日志消息。

然后运行pod install。有关CocoaPods的安装和使用详情,请访问[其官方网站][cocoapods]。

注意:在CocoaPods 1.4.0之前,无法使用混合Swift版本的多个pod。你可能需要确保每个pod都配置了正确的Swift版本(检查工作空间中pod项目的目标)。如果你手动调整了一个项目的Swift版本,下次运行pod install时它会重置。你可以在podfile中添加一个post_install钩子来自动设置正确的Swift版本。这在很大程度上未经测试,我不确定这是一个好的解决方案,但似乎可行:

post_install do |installer|
    installer.pods_project.targets.each do |target|
        if ['SomeTarget-iOS', 'SomeTarget-watchOS'].include? "#{target}"
            print "将#{target}的SWIFT_VERSION设置为4.2\n"
            target.build_configurations.each do |config|
                config.build_settings['SWIFT_VERSION'] = '4.2'
            end
        else
            print "将#{target}的SWIFT_VERSION设置为未定义(Xcode将自动解析)\n"
            target.build_configurations.each do |config|
                config.build_settings.delete('SWIFT_VERSION')
            end
        end
    end

    print "将默认SWIFT_VERSION设置为3.2\n"
    installer.pods_project.build_configurations.each do |config|
        config.build_settings['SWIFT_VERSION'] = '3.2'
    end
end

当然,你可以调整它以适应你的需求。

[Swift包管理器][swiftpm]

在你的包的依赖项中添加以下条目:

.Package(url: "https://github.com/DaveWoodCom/XCGLogger.git", majorVersion: 7)

向后兼容性

使用:

XCGLogger版本7.1.5用于Swift 5.0
XCGLogger版本6.1.0用于Swift 4.2
XCGLogger版本6.0.4用于Swift 4.1
XCGLogger版本6.0.2用于Swift 4.0
XCGLogger版本5.0.5用于Swift 3.0-3.2
XCGLogger版本3.6.0用于Swift 2.3
XCGLogger版本3.5.3用于Swift 2.2
XCGLogger版本3.2用于Swift 2.0-2.1
XCGLogger版本2.x用于Swift 1.2
XCGLogger版本1.x用于Swift 1.1及以下版本。

基本用法(快速入门)

这种快速入门方法旨在让你快速上手使用日志记录器。然而,你应该使用下面的高级用法来充分利用这个库。

将XCGLogger项目作为子项目添加到你的项目中,并将适当的库添加为你的目标的依赖项。在你的目标的General选项卡下,将XCGLogger.framework和ObjcExceptionBridging.framework添加到Embedded Binaries部分。

然后,在每个源文件中:

import XCGLogger

在你的AppDelegate(或其他全局文件)中,声明一个指向默认XCGLogger实例的全局常量。

let log = XCGLogger.default

在

application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]? = nil) // iOS, tvOS

或

applicationDidFinishLaunching(_ notification: Notification) // macOS

函数中,配置你需要的选项:

log.setup(level: .debug, showThreadName: true, showLevel: true, showFileNames: true, showLineNumbers: true, writeToFile: "path/to/file", fileLevel: .debug)

writeToFile: 的值可以是 String 或 URL。如果文件已存在，在使用前会被清空。省略该参数或设置为 nil 则只将日志输出到控制台。您可以使用 fileLevel: 参数为文件输出设置不同的日志级别。将其设置为 nil 或省略它则使用与控制台相同的日志级别。

然后，当您想记录日志时，使用以下便捷方法之一：

log.verbose("详细信息，通常在处理特定问题时有用")
log.debug("调试信息")
log.info("信息消息，可能对查看控制台的高级用户有用")
log.notice("通知消息")
log.warning("警告消息，可能表示潜在错误")
log.error("发生错误，但可恢复，仅提供发生情况的信息")
log.severe("发生严重错误，可能即将崩溃")
log.alert("发生警报错误，日志目标可以设置为向某人发送邮件")
log.emergency("发生紧急错误，日志目标可以设置为向某人发送短信")

不同的方法设置消息的日志级别。XCGLogger 只会打印日志级别大于或等于其当前设置的日志级别的消息。因此，级别为 .error 的日志记录器只会输出级别为 .error、.severe、.alert 或 .emergency 的日志消息。

高级用法（推荐）

XCGLogger 旨在简单易用，只需上述 2 行代码即可快速启动。但它也允许更大程度的控制和灵活性。

日志记录器可以配置为将日志消息传递到各种目标。使用上面的基本设置，日志记录器会将日志消息输出到标准的 Xcode 调试控制台，如果提供了路径，还可以选择输出到文件。您很可能希望将日志发送到更有趣的地方，比如 Apple 系统控制台、数据库、第三方服务器或其他应用程序，如 NSLogger。这可以通过向日志记录器添加目标来实现。

以下是配置日志记录器以输出到 Apple 系统日志和文件的示例。

// 创建一个没有目标的日志记录器对象
let log = XCGLogger(identifier: "advancedLogger", includeDefaultDestinations: false)

// 为系统控制台日志创建一个目标（通过 NSLog）
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

// 将目标添加到日志记录器
log.add(destination: systemDestination)

// 创建一个文件日志目标
let fileDestination = FileDestination(writeToFile: "/path/to/file", 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

// 将目标添加到日志记录器
log.add(destination: fileDestination)

// 在日志开头添加基本的应用信息、版本信息等
log.logAppDetails()

您可以根据需要为每个日志目标配置不同的选项。

另一种常见的使用模式是有多个日志记录器，比如一个用于 UI 问题，一个用于网络，另一个用于数据问题。

每个日志目标可以有自己的日志级别。为了方便起见，您可以在日志对象本身上设置日志级别，它会将该级别传递给每个目标。然后为需要不同级别的目标单独设置。

注意：一个目标对象只能添加到一个日志记录器对象，将其添加到第二个会从第一个中移除它。

使用闭包进行初始化

或者，您可以使用闭包来初始化全局变量，以便所有初始化都在一个地方完成

let log: XCGLogger = {
    let log = XCGLogger(identifier: "advancedLogger", includeDefaultDestinations: false)

    // 根据需要自定义
    
    return log
}()

注意：这会延迟创建日志对象，也就是说直到真正需要时才会创建。这会延迟应用信息详情的初始输出。因此，如果您在应用启动时没有立即记录日志，我建议通过在 didFinishLaunching 方法顶部添加 let _ = log 行来强制创建日志对象。

记录任何内容

您可以记录字符串：

log.debug("你好！")

或者几乎任何您想要的内容：

log.debug(true)
log.debug(CGPoint(x: 1.1, y: 2.2))
log.debug(MyEnum.Option)
log.debug((4, 2))
log.debug(["Device": "iPhone", "Version": 7])

过滤日志消息

XCGLogger 4 的新功能是，您现在可以创建过滤器应用于日志记录器（或特定目标）。创建并配置您的过滤器（示例如下），然后通过将可选的 filters 属性设置为包含过滤器的数组，将它们添加到日志记录器或目标对象。过滤器按照它们在数组中的顺序应用。在处理过程中，每个过滤器都会被询问是否应该从日志中排除该日志消息。如果任何过滤器排除了日志消息，它就会被排除。过滤器无法撤销另一个过滤器的排除。

如果目标的 filters 属性为 nil，则使用日志的 filters 属性。要让一个目标记录所有内容，而让所有其他目标过滤某些内容，请将过滤器添加到日志对象，并将该目标的 filters 属性设置为空数组 []。

注意：与目标不同，您可以将同一个过滤器对象添加到多个日志记录器和/或多个目标。

按文件名过滤

要排除特定文件的所有日志消息，可以创建一个排除过滤器，如下所示：

log.filters = [FileNameFilter(excludeFrom: ["AppDelegate.swift"], excludePathWhenMatching: true)]

excludeFrom: 接受 Array<String> 或 Set<String>，因此您可以同时指定多个文件。

excludePathWhenMatching: 默认为 true，因此除非您也想匹配路径，否则可以省略它。

要仅包含特定文件集的日志消息，请使用 includeFrom: 初始化器创建过滤器。也可以通过切换 inverse 属性将排除过滤器转换为包含过滤器。

按标签过滤

为了按标签过滤日志消息，您当然必须能够为日志消息设置标签。现在，每个日志消息都可以附加额外的用户定义数据，供过滤器（和/或格式化器等）使用。这通过 userInfo: Dictionary<String, Any> 对象处理。字典键应该是命名空间字符串，以避免与未来添加的内容发生冲突。官方键以 com.cerebralgardens.xcglogger 开头。可以通过 XCGLogger.Constants.userInfoKeyTags 访问标签键。您肯定不想每次都输入这么长的内容，所以可以创建一个全局快捷方式：let tags = XCGLogger.Constants.userInfoKeyTags。现在您可以轻松地为日志添加标签：

let sensitiveTag = "Sensitive"
log.debug("一条带标签的日志消息", userInfo: [tags: sensitiveTag])

标签的值可以是 Array<String>、Set<String> 或只是 String，取决于您的需求。在过滤时，它们的工作方式都相同。根据您的工作流程和使用情况，您可能会创建更快速的方法来设置 userInfo 字典。请参阅下面的混合搭配部分了解其他可能的快捷方式。

现在您的日志已经标记，您可以轻松进行筛选：

log.filters = [TagFilter(excludeFrom: [sensitiveTag])]

就像 FileNameFilter 一样，您可以使用 includeFrom: 或切换 inverse 来仅包含具有指定标签的日志消息。

按开发者筛选

按开发者筛选与按标签筛选完全相同，只是使用 XCGLogger.Constants.userInfoKeyDevs 作为 userInfo 键。事实上，这两种筛选器都是 UserInfoFilter 类的子类，您可以用它来创建其他筛选器。请参阅下面的扩展 XCGLogger部分。

混合搭配

在有多个开发者的大型项目中，您可能希望开始标记日志消息，并指明添加该消息的开发者。

虽然 userInfo 字典非常灵活，但使用起来可能有些繁琐。有几种可能的方法可以简化操作。我自己还在测试这些方法，所以它们还不是库的正式部分（我很乐意收到反馈或其他建议）。

我创建了一些实验性代码来帮助创建 UserInfo 字典。（如果使用 CocoaPods，请包含可选的 UserInfoHelpers 子规范）。查看 iOS Demo 应用以了解其使用方法。

有两个符合 UserInfoTaggingProtocol 协议的结构体。Tag 和 Dev。

您可以为每个结构体创建适合您项目的扩展。例如：

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")
}

除了这些类型，还有一个重载的 | 运算符，可以用来将它们合并成与日志调用的 UserInfo: 参数兼容的字典。

然后您可以这样记录消息：

log.debug("A tagged log message", userInfo: Dev.dave | Tag.sensitive)

目前我看到这些 UserInfoHelpers 存在一些问题，这就是为什么我暂时将其设为可选/实验性的原因。我很乐意听到评论/改进建议。

重载的 | 运算符合并字典，只要没有 Set。如果其中一个字典包含 Set，它会使用其中一个，而不进行合并。如果两边对同一个键都有集合，则优先使用左侧的。
由于 userInfo: 参数需要一个字典，您不能传入单个 Dev 或 Tag 对象。您需要至少使用两个并用 | 运算符才能自动转换为兼容的字典。例如，如果您只想要一个 Tag，必须手动访问 .dictionary 参数：userInfo: Tag("Blah").dictionary。

选择性执行代码

所有日志方法都基于闭包操作。使用与 Swift 的 assert() 函数相同的语法糖，这种方法确保我们不会浪费资源构建不会输出的日志消息，同时保持调用站点的整洁。

例如，如果调试日志级别被抑制，以下日志语句不会浪费资源：

log.debug("The description of \(thisObject) is really expensive to create")

同样，假设您需要遍历一个循环以在记录结果之前进行一些计算。在 Objective-C 中，您可以将该代码块放在 #if #endif 之间，防止代码运行。但在 Swift 中，之前您仍然需要处理该循环，浪费资源。使用 XCGLogger 就像这样简单：

log.debug {
    var total = 0.0
    for receipt in receipts {
        total += receipt.total
    }

    return "Total of all receipts: \(total)"
}

如果您希望选择性执行代码而不生成日志行，请返回 nil，或使用以下方法之一：verboseExec、debugExec、infoExec、warningExec、errorExec 和 severeExec。

自定义日期格式

您可以创建自己的 DateFormatter 对象并将其分配给记录器。

let dateFormatter = DateFormatter()
dateFormatter.dateFormat = "MM/dd/yyyy hh:mma"
dateFormatter.locale = Locale.current
log.dateFormatter = dateFormatter

用颜色增强日志消息

XCGLogger 支持向日志消息添加格式化代码，以在各个地方启用颜色。最初的选项是使用 XcodeColors 插件。然而，Xcode（从版本 8 开始）不再官方支持插件。您仍然可以查看彩色日志，只是暂时不能在 Xcode 中查看。您可以使用 ANSI 颜色支持为 fileDestination 对象添加颜色，并通过终端窗口查看日志。这给您一些额外的选项，如添加粗体、斜体或（请不要）闪烁！

启用后，每个日志级别都可以有自己的颜色。这些颜色可以根据需要自定义。如果使用多个记录器，您也可以将每个记录器设置为自己的颜色。

设置 ANSI 格式化程序的示例：

if let fileDestination: FileDestination = log.destination(withIdentifier: XCGLogger.Constants.fileDestinationIdentifier) as? FileDestination {
    let ansiColorLogFormatter: ANSIColorLogFormatter = ANSIColorLogFormatter()
    ansiColorLogFormatter.colorize(level: .verbose, with: .colorIndex(number: 244), options: [.faint])
    ansiColorLogFormatter.colorize(level: .debug, with: .black)
    ansiColorLogFormatter.colorize(level: .info, with: .blue, options: [.underline])
    ansiColorLogFormatter.colorize(level: .notice, with: .green, options: [.italic])
    ansiColorLogFormatter.colorize(level: .warning, with: .red, options: [.faint])
    ansiColorLogFormatter.colorize(level: .error, with: .red, options: [.bold])
    ansiColorLogFormatter.colorize(level: .severe, with: .white, on: .red)
    ansiColorLogFormatter.colorize(level: .alert, with: .white, on: .red, options: [.bold])
    ansiColorLogFormatter.colorize(level: .emergency, with: .white, on: .red, options: [.bold, .blink])
    fileDestination.formatters = [ansiColorLogFormatter]
}

与过滤器一样，您可以为多个记录器和/或多个目标使用相同的格式化程序对象。如果目标的 formatters 属性为 nil，则将使用记录器的 formatters 属性。

有关创建自定义格式化程序的信息，请参阅下面的扩展 XCGLogger。

替代配置

通过使用 Swift 构建标志，可以在调试与暂存/生产环境中使用不同的日志级别。转到 Build Settings -> Swift Compiler - Custom Flags -> Other Swift Flags，并将 -DDEBUG 添加到 Debug 条目。

#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

您可以以类似的方式设置任意数量的选项。有关基于选项使用不同日志目标的示例，请查看更新后的 iOSDemo 应用，搜索 USE_NSLOG。

后台日志处理

默认情况下，提供的日志目标将在调用它们的线程上处理日志。这是为了确保在调试应用程序时立即显示日志消息。您可以在日志调用之后立即添加断点，并在断点触发时看到结果。然而，如果您不是在主动调试应用程序，在当前线程上处理日志可能会影响性能。您现在可以指定一个目标在您选择的调度队列上处理其日志（或者甚至使用提供的默认队列）。

fileDestination.logQueue = XCGLogger.logQueue

或者甚至

fileDestination.logQueue = DispatchQueue.global(qos: .background)

这在与上面的备用配置方法结合使用时效果极佳。

#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

追加到现有日志文件

在使用日志记录器的高级配置时（参见上面的高级用法），您现在可以指定日志记录器追加到现有日志文件，而不是自动覆盖它。

在初始化FileDestination对象时添加可选的shouldAppend:参数。您还可以添加appendMarker:参数，在日志文件中添加一个标记，指示您的应用程序新实例开始追加的位置。如果省略该参数，默认会添加-- ** ** ** --。将其设置为nil可跳过添加标记。

let fileDestination = FileDestination(writeToFile: "/path/to/file", identifier: "advancedLogger.fileDestination", shouldAppend: true, appendMarker: "-- 重新启动应用 --")

自动日志文件轮换

在记录到文件时，您可以选择自动将日志文件轮换到归档目标，并让日志记录器自动在旧文件的位置创建一个新的日志文件。

使用AutoRotatingFileDestination类创建一个目标，并设置以下属性：

targetMaxFileSize：文件大小超过此值时自动轮换

targetMaxTimeInterval：经过这么多秒后自动轮换

targetMaxLogFiles：保留的归档日志文件数量，较旧的文件会自动删除

这些都是日志记录器的指导方针，而不是硬性限制。

扩展XCGLogger

您可以创建替代日志目标（除了内置的目标）。您的自定义日志目标必须实现DestinationProtocol协议。实例化您的对象，配置它，然后使用add(destination:)将其添加到XCGLogger对象中。有两个基本目标类（BaseDestination和BaseQueuedDestination）您可以继承，它们会为您处理大部分过程，只需要您在自定义类中实现一个额外的方法。可以参考ConsoleDestination和FileDestination作为示例。

您还可以创建自定义过滤器或格式化器。可以将提供的版本作为起点。请注意，过滤器和格式化器有能力在处理日志消息时对其进行修改。这意味着您可以创建一个过滤器来删除密码、突出显示特定单词、加密消息等。

贡献

XCGLogger之所以成为Swift最佳的日志记录器，是因为像您这样的社区贡献。有许多方式可以帮助它继续变得更好。

在[GitHub][github-xcglogger]上给项目加星。
报告您发现的问题/错误。
提出功能建议。
提交拉取请求。
下载并安装我的一个应用：[https://www.cerebralgardens.com/apps/][cerebral-gardens-apps] 试试我最新的应用：[All the Rings][all-the-rings]。
您可以访问我的[Patreon][patreon-davewoodx]并提供财务支持。

注意：提交拉取请求时，请使用多个小提交而不是一个大提交。当需要合并几个拉取请求以发布新版本时，这样会更容易合并。