Evergreen

最自然的 Swift 日志

Evergreen 是一个用 Swift 编写的日志框架。它设计得与您的预期一样，同时非常灵活，您可以让它按照您希望的方式工作。

将 Evergreen 日志集成到您的 Swift 项目中，用 Evergreen 的多功能日志函数替换那些普通的 print() 语句，这些函数可以轻松地调整输出的详细程度，并将日志记录到多个目的地（例如文件），具有自定义格式，甚至可以测量时间。

import Evergreen

log("Hello World!", forLevel: .info)

[AppDelegate.swift|INFO] Hello World!

Evergreen 日志非常适合用于任何 Swift 项目，但对于开发框架尤其有用。为您的框架用户提供轻松调整框架生成的输出详细程度的机会。

• 关于日志
• 安装
• 用法
  • 不配置日志
  • 使用日志级别
  • 使用日志层次结构
  • 使用环境变量进行配置
  • 在事件旁边记录错误
  • 测量时间
  • 仅记录事件一次

• 高级用法
  • 使用处理器
  • 格式化

• 联系
• 许可证

关于日志

日志 是跟踪软件运行时发生的事件的手段。软件的开发者会在代码中添加日志调用，以指示某些事件已经发生。事件通过描述性消息来描述，该消息可以包含可选的变量数据（即对于事件发生的每次可能不同的数据）。事件还具有重要性，这是开发者赋予事件的；重要性也可以称为 级别 或 严重性。

—— 来自 Python 文档。

虽然对每个人来说这都不是日志的最佳用途。有些人会说：

日志 是切割、滑动、现场加工以及将树木或原木装上卡车或骨架车的过程。

—— 来自 维基百科。

让我们先关注 Python 的人告诉我们的内容。他们似乎很清楚他们在说什么。

安装

Swift 包管理器

您还可以使用包含在 Swift 包管理器 中的功能。只需将 Evergreen 作为依赖项添加到包描述中，就像这样

import PackageDescription

let package = Package(
    name: "HelloWorld",
    dependencies: [
        .Package(url: "https://github.com/knly/Evergreen.git", majorVersion: 0),
        // ...
    ]
)

手动操作

您还可以手动将 Evergreen 集成到您的项目中

1. 将 Evergreen 添加为 子模块

   $ git submodule add https://github.com/knly/Evergreen.git

2. 将 Evergreen.xcodeproj 拖放到您项目的文件导航器中。

3. 在 通用 部分下的目标配置中，将 Evergreen.framework 添加到 嵌入的二进制文件

用法

注意：打开 Evergreen.xcworkspace 并查看 Evergreen.playground 以体验 Evergreen 的更多交互式功能。您还可以在项目工作区中创建一个 Playground 并 导入 Evergreen 以亲自尝试。

无配置日志记录

import Evergreen

log("Hello World!")

您可以在没有任何配置的情况下记录事件，并看到格式优美的消息在控制台中显示。这仅适用于非常快速和基本的使用。继续阅读，了解 Evergreen 的更复杂日志记录选项。

使用日志级别

您可以将事件分配给以下之一对应的 日志级别 的重要性或严重性

• 关键：意外事件，可能导致严重问题。您可能需要在半夜处理这些问题。
• 错误：意外事件，未由您的软件处理。有人应该立即告诉您这些。
• 警告：意外事件，但可能不会影响软件的运行时。您可能最终需要调查这些。
• 信息：文档软件生命周期的常规事件。
• 调试：用于了解软件流的命令，主要用于调试目的。
• 详细：当需要时提供额外上下文的环境详细信息。

处理事件的事件记录器也有一个日志级别。如果事件日志级别低于事件记录器的，则不会记录。

除了上述日志级别之外，事件记录器还可以有以下的日志级别。仅当用于特定用例时，对这些事件进行赋值才有意义。

• 所有：记录所有事件。
• 关闭：不记录任何事件。

使用日志级别，您可以控制软件的详细程度。一个常见的用例是在开发期间使用较低的日志级别，并在发布环境中提高它，或者根据软件的特定部分和不同的日志记录目的地（如控制台或文件）进行调整。

对于基本配置，您可以调整 Evergreen 的默认日志级别。关于如何更细致地控制日志级别，请参阅下面的 记录器层次结构。

Evergreen.logLevel = .debug

// These events will be logged, because their log level is >= .debug
log("Debug", forLevel: .debug)
log("Info", forLevel: .info)
log("Warning", forLevel: .warning)
log("Error", forLevel: .error)
log("Critical", forLevel: .critical)

// These events will not be logged, because their log level is < .debug
log("Verbose", forLevel: .verbose)

每个日志级别都有一个相应的日志函数，以便于使用。

debug("Debug") // equivalent to log("Debug", forLevel: .debug)
info("Info") // equivalent to log("Info", forLevel: .info)
// ...

使用记录器层次结构

您通常会使用 记录器 而不是全局函数来记录事件。记录器始终是层次结构的一部分，并从其父级继承属性，如日志级别。这样，您可以提供一个默认配置，并根据软件的特定部分进行调整。

这在开发过程中尤其有用，可以帮助您降低当前正在工作的软件部分的日志级别。

每个日志记录器都有一个用于识别任何给定事件源的 key。在其层次结构中，该 key 展开为点分隔的 key 路径，例如“父.子”。

当然，您可以手动构建自己的层次结构，但 Evergreen 提供了一种便捷的方式供您利用这一强大的功能。

• 默认日志记录器 是日志记录器层次结构的根，可通过使用 Evergreen.defaultLogger 常量检索。使用它设置默认的日志级别。全局变量 Evergreen.logLevel 也引用默认的日志记录器。
• 使用全局 Evergreen.getLogger 函数或 Logger.child 实例方法检索适当的日志记录器。提供描述事件相关的软件部分的 key 路径，例如 "MyModule.MyType"。这些方法将始终为给定的 key 路径返回相同的日志记录器实例，并在尚不存在时建立日志记录器层次结构。

使用存储的常量属性来使给定的类型可用是一个方便的做法。

import Evergreen

class MyType {

    let logger = Evergreen.getLogger("MyModule.MyType")

    init() {
        self.logger.debug("Initializing...")
    }

}

建立日志记录器层次结构后，您可以调整其部分的日志配置。

Evergreen.logLevel = .warning // Set the `defaultLogger`'s log level to .warning
let logger = Evergreen.getLogger("MyModule") // Retrieve the logger with key "MyModule" directly descending from the default logger
logger.logLevel = .debug // We are working on this part of the software, so set its log level to .debug

注意： 对于生产环境，您可以在 AppDelegate 的 application:didFinishLaunchingWithOptions: 方法中执行此配置。按以下部分所述，将临时日志级别调整作为环境变量配置最好。

使用环境变量进行配置

临时配置日志记录器层次结构的首选方式是使用环境变量。这样做可以方便地为当前正在工作的软件部分启用更详细的日志记录。在 Xcode 中，从工具栏的下拉菜单中选择您的目标，选择 编辑方案... > 运行 > 参数 并将环境变量添加到列表中。然后调用

Evergreen.configureFromEnvironment()

每个以 Evergreen 为前缀的环境变量都被评估为一个日志记录器 key 路径，并分配与之对应的日志级别。值应匹配日志级别的描述，例如 Debug 或 Warning。

有效的环境变量声明可以是 Evergreen = Debug 或 Evergreen.MyLogger = Verbose。

在您的事件旁边记录错误

您可以将任何符合 Swift 的 Error 类型（如 NSError）的错误传递给 Evergreen 的日志函数，无论是作为消息还是作为单独的 error: 参数。

let error: Error // some error
debug("Something unexpected happened here!", error: error)

衡量时间

您可以使用 tic 和 toc 易于测量两个事件之间的时间。

tic(andLog: "Starting expensive operation...", forLevel: .debug)
// ...
toc(andLog: "Completed expensive operation!", forLevel: .info)

[Default|DEBUG] Starting expensive operation...
[Default|INFO] Completed expensive operation! [ELAPSED TIME: 0.0435580015182495s]

您还可以使用 timerKey 参数进行嵌套计时。

tic(andLog: "Starting expensive operation...", forLevel: .debug, timerKey: "expensiveOperation")
for var i=0; i<10; i++ {
    tic(andLog: "\(i+1). iteration...", forLevel: .verbose, timerKey: "iteration")
    // ...
    toc(andLog: "Done!", forLevel: .verbose, timerKey: "iteration")
}
toc(andLog: "Completed expensive operation!", forLevel: .info, timerKey: "expensiveOperation")

仅记录一次事件

您可以通过在日志调用中将一个 key 与类似事件关联来防止记录过多类似事件，例如：

debug("Announcing this once!", onceForKey: "announcement")

高级用法

使用处理程序

当日志记录器确定应处理事件时，它将该事件传递给其 处理程序。处理程序使用其 格式化程序 从事件检索一个人类可读的 记录，然后 发布 该记录。Handler 的子类以不同的方式发布记录。

• ConsoleHandler 将记录打印到控制台。
• FileHandler 将记录写入文件。
• StenographyHandler 将记录追加到内存中的数组。

您可以在自己的子类中覆盖 emit 方法来实现所需的任何自定义行为，例如将其发送到服务器。

Evergreen 的 defaultLogger 默认附加了 ConsoleHandler，因此其层次结构中的每个事件都将记录到控制台。您可以通过将适当的日志器 handlers 数组中添加额外处理程序来轻松添加其他处理程序。

let logger = Evergreen.defaultLogger
let stenographyHandler = StenographyHandler()
logger.handlers.append(stenographyHandler)

您还可以设置处理程序的 logLevel，以增加额外的过滤级别。

格式化

Evergreen 的 Formatter 类实现了您调整日志记录格式的一种便捷方式。

默认实现 string(from eventイベント: Event＜M＞） 方法（您也可以在子类中覆盖它），使用列表 components: [Formatter.Component] 从事件构建记录，这些是从 Formatter.Component 枚举的实例中构建的。

let simpleFormatter = Formatter(components: [ .Text("["), .Logger, .Text("|"), .LogLevel, .Text("] "), .Message ])
let consoleHandler = ConsoleHandler(formatter: simpleFormatter)
Evergreen.defaultLogger.handlers = [ consoleHandler ]

联系

Evergreen 是由 Nils Leif Fischer 创建和维护的。

我会非常感激一些关于 API 和架构的专业意见。请通过电子邮件（），在 Gitter 上或通过 提交问题 让我知道任何建议。

许可

Evergreen 发布在 MIT 许可之下。有关详细信息，请参阅 LICENSE.md。