该框架利用 Swift 5 中引入的功能，使从 Swift 代码与 Apple 系统日志进行交互变得自然而简单。还包括面向 Swift 的便捷 API，用于日志记录 signposts 和 activity tracing，使其使用起来同样自然。

日志管理器 OSLogManager 是一个工厂，用于提供配置好的 OSLog 实例。

let log = OSLogManager.for(category: "My Application")

可以通过提供配置块来更改管理器的属性，以实现进一步的配置。

let logManager = OSLogManager.for(category: "My Application") { logManager in
  logManager.baseCategory = "General"
}

OSLogManager 和 OSLog 提供了前缀，可用于帮助在复杂的输出中识别日志消息。默认值使用 emoji 来唯一标识每个日志级别。对于自定义，可以使用全局变量 logConfig 完成应用程序范围内的日志记录前缀配置。

OSLogTrace.logConfig.prefix.error = "☢️"

日志记录接口使用 os.log 包提供的标准 OSLog 类。它针对每个日志级别进行了类型化方法的扩展，并采用 LogMessage 来提供使用 Swift 5 的字符串插值魔法的参数化日志消息。

extension OSLog {
  public func log(type: OSLogType, _ message: @autoclosure () -> LogMessage)
  public func log(_ message: @autoclosure () -> LogMessage) 
  public func info(_ message: @autoclosure () -> LogMessage)
  public func debug(_ message: @autoclosure () -> LogMessage)
  public func error(_ message: @autoclosure () -> LogMessage)
  public func fault(_ message: @autoclosure () -> LogMessage)
}

使用 LogMessage 生成参数化日志消息非常简单，并且由于 Swift 5 的字符串插值支持（通过 ExpressibleByStringInterpolation），可以使用标准的 Swift 语法创建它们...

let audience = "World"
log.info("Hello \(audience)")

这个简单的日志消息正确地将 audience 参数作为 *动态参数* 传递给 OSLog。这会将消息创建推迟到需要时，并允许我们控制系统日志如何显示和报告这些参数。

Apple 的系统日志可以解释某些类型的数据，而 OSLogTrace 的日志记录扩展自然地公开了这种能力。

let completedBytes = 2.4 * 1024 * 1024
log.debug("Downloaded \(completedBytes, unit: .bytes)")

日志将使用最佳可用单位显示该值。在这种特定情况下，它将被报告为

Downloaded 2.4 MiB

Apple 的系统日志也支持隐私。将参数标记为 private 将确保此信息不会长期存储，并在正确的上下文中被编辑。

let accountEmail = "test@example.com"
log.info("Sign-in from \(accountEmail, view: .private)")

Signposts 是 Apple 的日志记录增强功能，用于调试和分析，与 OSLog 并肩工作。可以使用 OSLogTrace 的便捷 API 创建和标记 Signpost ID。

let log: OSLog = ...
let spid = log.signpostID()  // Create ID
log.event("Stage 1", spid)   // Mark "event"
log.event("Stage 1", spid, "A \(parameterized) message") // Mark "event" with a log message

let log: OSLog = ...
let sp = log.signpost()   // Create a Signpost with a unique signpost ID
sp.event("Stage 1")       // Mark "event"
sp.event("Stage 1", "A \(parameterized) message") // Mark "event" with a log message

Activity("Download Email") {
  // download the emails
}

let emailDownload = Activity("Download Email")

emailDownload.run {
  // download some emails
}

...

emailDownload.run {
  // download some emails
}

let emailDownload = Activity("Download Email")

let scope = emailDownload.enter()
defer { scope.leave() }

// download some emails

📒OSLogTrace

用于 Apple 系统日志、Signposts 和 Activity 追踪的 Swift API

日志记录

OSLogManager

OSLog

LogMessage

显示

隐私

Signposts

Activity 追踪