XCGLogger 7.1.5

XCGLogger 7.1.5

×

测试已测试✓
Lang语言 SwiftSwift
许可 MIT
发布上次发布2024年5月
SPM支持SPM✓

由Dave Wood维护。

XCGLogger 7.1.5

XCGLogger

badge-language badge-platforms badge-license

badge-travis badge-swiftpm badge-cocoapods badge-carthage

badge-mastodon badge-twitter

badge-sponsors badge-patreon

tl;dr

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

Swift不包含C预处理器，因此开发者无法像在Objective-C中那样使用调试日志#define宏。这意味着我们传统的生成良好调试日志的方式不再适用。仅仅使用普通的print调用意味着您会丢失很多有用的信息，或者需要编写更多的代码。

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

从以下内容开始

简单消息

到以下内容

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

示例

Example

通讯（感谢AlamoFire）

  • 如果您需要帮助，请使用Stack Overflow（标签'xcglogger'>）。
  • 如果您想问一个一般性的问题，请使用Stack Overflow。
  • 如果您发现了bug，请提交一个issue。
  • 如果您有功能请求，请提交一个issue。
  • 如果您想贡献，请提交一个pull request。
  • 如果您使用XCGLogger，请在GitHub上为项目Star。

安装

Git Submodule

执行

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

在您的仓库文件夹中。

Carthage

请在您的Cartfile中添加如下行。

github "DaveWoodCom/XCGLogger" ~> 7.0.1

然后运行carthage update --no-use-binaries或简单地运行carthage update。关于Carthage的安装和使用详情，请访问它的项目页面。

运行Swift 5.0及以上版本的开发者需要在携入文件的Copy Carthage Frameworks构建阶段添加$(SRCROOT)/Carthage/Build/iOS/ObjcExceptionBridging.framework。

CocoaPods

将以下类似内容添加到您的Podfile中。您可能需要根据平台、版本/分支等进行调整。

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

pod 'XCGLogger', '~> 7.0.1'

仅指定pod XCGLogger将包含核心框架。我们开始添加子规范，让您也可以包含可选组件

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

然后运行pod install。关于CocoaPods的安装和使用详情，请访问它的官方网页。

注意：在CocoaPods 1.4.0之前，无法使用Swift版本混合的多个pods。您可能需要确保每个pod都配置了正确的Swift版本（检查您的工作区中pods项目的目标）。如果您手动调整项目的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 "Setting #{target}'s SWIFT_VERSION to 4.2\n"
            target.build_configurations.each do |config|
                config.build_settings['SWIFT_VERSION'] = '4.2'
            end
        else
            print "Setting #{target}'s SWIFT_VERSION to Undefined (Xcode will automatically resolve)\n"
            target.build_configurations.each do |config|
                config.build_settings.delete('SWIFT_VERSION')
            end
        end
    end

    print "Setting the default SWIFT_VERSION to 3.2\n"
    installer.pods_project.build_configurations.each do |config|
        config.build_settings['SWIFT_VERSION'] = '3.2'
    end
end

当然，您可以调整它以满足您的需求。

Swift 包管理器

将以下条目添加到你的包依赖中

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

向后兼容性

使用

  • XCGLogger 版本 7.0.1 用于 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 项目作为子项目添加到您的项目中，并将适当的库作为您的目标的依赖项。在您的目标的通用选项卡下，将 XCGLogger.framework 和 ObjcExceptionBridging.framework 添加到 嵌入的二进制文件部分。

然后，在每个源文件中

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("A verbose message, usually useful when working on a specific problem")
log.debug("A debug message")
log.info("An info message, probably useful to power users looking in console.app")
log.notice("A notice message")
log.warning("A warning message, may indicate a possible error")
log.error("An error occurred, but it's recoverable, just info about what happened")
log.severe("A severe error occurred, we are likely about to crash now")
log.alert("An alert error occurred, a log destination could be made to email someone")
log.emergency("An emergency error occurred, a log destination could be made to text someone")

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

高级用法（推荐）

XCGLogger旨在简单易用，只需在代码中添加2行即可快速运行。但同时也提供了更多的控制和灵活性。

可以将日志记录器配置为将日志消息发送到各种目标。使用上述基本设置，日志记录器将输出日志消息到标准的Xcode调试控制台，并在提供路径的情况下可选地将消息输出到文件。您很可能希望将日志发送到更有趣的地方，例如Apple系统控制台、数据库、第三方服务器，或者另一个应用程序，如NSLogger。这可以通过将目标添加到日志记录器中来实现。

以下是一个配置日志记录器同时输出到Apple系统日志和文件的例子。

// Create a logger object with no destinations
let log = XCGLogger(identifier: "advancedLogger", includeDefaultDestinations: false)

// Create a destination for the system console log (via NSLog)
let systemDestination = AppleSystemLogDestination(identifier: "advancedLogger.systemDestination")

// Optionally set some configuration options
systemDestination.outputLevel = .debug
systemDestination.showLogIdentifier = false
systemDestination.showFunctionName = true
systemDestination.showThreadName = true
systemDestination.showLevel = true
systemDestination.showFileName = true
systemDestination.showLineNumber = true
systemDestination.showDate = true

// Add the destination to the logger
log.add(destination: systemDestination)

// Create a file log destination
let fileDestination = FileDestination(writeToFile: "/path/to/file", identifier: "advancedLogger.fileDestination")

// Optionally set some configuration options
fileDestination.outputLevel = .debug
fileDestination.showLogIdentifier = false
fileDestination.showFunctionName = true
fileDestination.showThreadName = true
fileDestination.showLevel = true
fileDestination.showFileName = true
fileDestination.showLineNumber = true
fileDestination.showDate = true

// Process this destination in the background
fileDestination.logQueue = XCGLogger.logQueue

// Add the destination to the logger
log.add(destination: fileDestination)

// Add basic app info, version info etc, to the start of the logs
log.logAppDetails()

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

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

每个日志目标可以有它自己的日志级别。作为一个便利，您可以在日志对象本身上设置日志级别，并且它会将该级别传递到每个目标。然后设置那些需要不同级别的目标。

注意：目的地对象只能添加到单个日志记录器对象中，将其添加到第二个将使其从第一个中删除。

使用闭包进行初始化

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

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

	// Customize as needed
    
    return log
}()

注意：这会延迟创建日志对象，这意味着它只有在实际需要时才会创建。这会延迟应用信息细节的初始输出。因此，如果您没有在应用启动时进行日志记录，建议您通过在didFinishLaunching方法的顶部添加一行let _ = log来强制创建日志对象。

记录任何内容

您可以记录字符串

log.debug("Hi there!")

或者几乎是您想记录的任何内容

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("A tagged log message", 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 示例应用程序以查看它的使用方法。

有两个结构遵循 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 看到一些当前问题，这就是为什么我现在将其作为可选/实验性版本。我最想听听您对改进的建议或建议。

  1. 可重载运算符 | 合并字典，只要它们没有 Set。如果其中一个字典包含一个 Set，它将使用其中之一，而不会合并它们。如果有相同的键对两边都有 Set，则优先考虑左侧。
  2. 由于 userInfo: 参数需要一个字典，因此您不能传递单个 Dev 或 Tag 对象。您需要至少使用两个与 | 运算符一起使用，以自动将其转换为兼容的字典。例如，如果您只想要一个标签，您必须手动访问 .dictionary 参数：userInfo: Tag("Blah").dictionary。

选择性执行代码

所有日志方法都在闭包上操作。与 Swift 的 assert() 函数使用相同的语法糖，这种方法确保我们不浪费资源构建根本不会输出的日志消息，同时保持干净的调用位置。

例如，以下日志语句在禁用调试日志级别的情况下不会浪费资源

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

同样，假设您需要遍历循环以执行一些计算后再记录结果。在 Objective-C 中，您可以在 和 #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 颜色支持来添加颜色到您的文件目的地对象，并通过终端窗口查看日志。这为您提供了额外的选项，例如添加粗体、斜体或（请不要）闪烁！

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

设置 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构建标志，可以在调试、预发布/生产中使用不同的日志级别。转到“构建设置”->“Swift编译器”->“自定义标志”->“其他Swift标志”，并在“调试”输入中添加-DDEBUG。

#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: "-- Relauched App --")

自动日志文件轮转

当记录到文件时，您可以选择自动将日志文件轮换到存档目标地点，并让记录器自动创建一个新日志文件代替旧文件。

使用AutoRotatingFileDestination类创建目标并设置以下属性

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

targetMaxTimeInterval：此秒数后自动轮换

targetMaxLogFiles：保留存档日志文件的数量，较老的文件将被自动删除

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

扩展 XCGLogger

您可以创建除内置的目标位置之外的替代日志目标位置。您的自定义日志目标必须实现DestinationProtocol协议。创建对象实例，对其进行配置，然后使用add(destination:)将其添加到XCGLogger对象中。有两个基础目标类（BaseDestination和BaseQueuedDestination），您可以从这些类中继承来处理大多数过程，您只需要在您的自定义类中实现一个额外的函数。查看ConsoleDestination和FileDestination作为示例。

您还可以创建自定义过滤器或格式化程序。以提供的版本作为起点。请注意，过滤器可以修改正在处理中的日志消息。这意味着您可以创建一个移除密码、突出显示特定单词、加密消息等的过滤器。

贡献

由于像您这样社区成员的贡献，XCGLogger是Swift中最好的记录器。有许多方式您可以帮助继续使其保持出色。

  1. 在GitHub上star该项目。
  2. 报告您发现的错误/问题。
  3. 建议功能。
  4. 提交pull请求。
  5. 下载并安装我的一个应用程序：https://www.cerebralgardens.com/apps/试我的最新应用：All the Rings。
  6. 您还可以访问我的Patreon并财务捐赠。

注意：在提交pull请求时，请使用多个小型提交而不是一个大型的提交。当需要合并多个pull请求以生成新版本时，这会更容易合并。

待办事项

  • 添加一些高级用例的更多示例
  • 添加更多的日志目标类型
  • 添加Objective-C支持
  • 添加Linux支持

更多

如果您觉得这个库很有帮助，那这个其他工具也肯定很有用

看门狗：https://watchdogforxcode.com/

此外，请查看我的一些其他项目

变更日志

变更日志现在在它自己的文件中：[CHANGELOG.md](CHANGELOG.md)