探索 Swift 中的日志记录

探索 Swift 中的日志记录

了解最新的 Swift 统一日志记录 API。了解如何在保留隐私的同时在 app 中记录事件和错误。利用功能强大但易读的数据格式化选项——这些都不会影响性能。我们将向你展示如何收集和处理日志消息，从而帮助你了解和更正 app 中的异常行为。

资源
- - 高清视频
  - 标清视频
相关视频

WWDC23
- 使用结构化日志进行调试
WWDC20
- Swift 的最新进展
下载

（你好 WWDC 2020）
你好欢迎来到 WWDC
欢迎观看《探索 Swift 中的日志记录》我叫 Ravi Kandhadai Madhavan 是 Apple 的一位工程师在这期讲座中我会为大家展示如何使用 Apple 的统一日志记录 API 也就是 os_log 来更轻松地调试你的 app 我会讲解如何从一台你可以访问的设备上采集日志我将操作演示可用于分析日志的工具来了解并修复你的 app 遇到的问题
我会介绍如何控制日志调用的性能以及使用格式化选项来改善日志消息的可读性
修复程序错误非常重要用户期望高质量的 app 是可靠的并且很少出现程序错误即使小程序错误也会导致不良用户体验不过有些程序错误会相对更难修正通常最让人无从下手的都是那些在开发过程中难以重现的错误
日志是查找和修复难以重现的程序错误的一款优秀工具它们会提供一系列线索让你甚至无需通过重现的方法就能够追查并了解一个程序错误现在我给大家展示我正在开发的 app 中一个难以重现的程序错误稍后我会演示如何通过添加日志记录来有助于了解并修复这个程序错误
我的 app 叫 Fruta 用户可以在上面购买奶昔我可以浏览这些奶昔轻点一款奶昔并购买
我最近在 app 中添加了一项“礼品卡”功能我创建了一个新标签用来浏览礼品卡我可以轻点一张卡片并使用 Apple Pay 购买当我滚动到这些卡片的底部后我的 app 就会与一个服务器通信并开始加载更多卡片当我通过轻点选中了一张卡片后我的 app 就会停止加载卡片并终止任何正在进行的通信但是我也可以返回并继续查看更多卡片大多数时候都可以正常运行不幸的是有时我会看到一个程序错误如果当 app 正在加载更多卡片时我轻点一张卡片加载有时候会失败并出现一个错误（错误：加载失败）这很令人沮丧因为发生时我并不在开发机器附近这种情况非常偶然所以我无法在调试器中重现在你的 app 中添加日志记录可以帮助你了解此类错误且无需在桌面上重现它们在 Xcode 12 中我们为统一日志记录引入了新的 Swift API 你可以使用这些 API 来记录你的 app 运行中发生的重要事件这些日志由操作系统进行归档所以之后你可以从设备上取回它们因为这些新的 API 十分高效所以它们可以被广泛使用且不会降低你的 app 运行速度
将日志记录添加到你的 app 只需简单的三步首先导入定义新日志记录 API 的“os”模块其次创建一个类型为“Logger”的实例为它传递一个子系统和分类这些会附加在 Logger 记录的每一条消息上
子系统通常是一个捆绑标识符有助于识别出来自你的 app 的消息你可以使用分类来进一步区分来源于程序不同部分的消息
这里我为 Logger 使用了“礼品卡”分类
第三通过在 Logger 实例上调用一个方法将日志记录添加到代码中有趣的位置这里每当我的 app 从服务器下载数据时我都添加一条日志
通过 Logger 你可以使用字符串插值将运行数据添加到日志消息中比如这里我为日志消息添加了一个任务标识符这就类似于调用打印功能
不过日志消息有一个关键的不同点和打印不一样日志消息不会被全部转换为字符串那样会非常慢相反编译器和日志记录资料库会协同工作来生成日志消息高度优化后的表示以充分利用所记录的数据类型使用优化后的表示你只需在实际显示日志消息时花费转换为字符串的成本日志消息可以包含的数据类型种类广泛你可以记录数值类型比如 Int 和 Double、Objective-C 对象以及任何其它类型只要它们符合 Swift 的 CustomStringConvertible 协议也就是说要想在日志消息中添加你自己的类型只需使其符合 CustomStringConvertible 在日志消息中添加运行数据时你要注意像是字符串或对象这样的非数值类型会在日志中被默认删改这么做是为了确保你的 app 在发布后并且在用户的设备上运行时日志不会显示任何个人信息
比如这里我在记录一条日志消息里面包含一位用户的银行账号是由字符串表示的在输出的日志中账号会被删改为“私密”
不过不处理敏感信息的数据可以在日志中被设置为可见当你记录运行数据时如图所示传递一个 .public 值给可选的隐私参数
现在日志就会显示数据内容了这里显示了奶昔的名称稍后我会介绍有关隐私的更多内容
当你的 app 记录一条消息时操作系统会以压缩形式将它储存在设备中你可以在你的 Mac 上使用“日志采集”命令来取回这些日志首先将你的设备连接到 Mac 接着使用设备选项从终端运行“日志采集”命令
根据你需要日志的时间点来提供一个开始时间通常是你看见第一个程序错误之前几分钟还要为储存日志存档提供一个文件名你可以在控制台 app 中通过双击日志存档来打开它们这个 app 让浏览和过滤日志都变得很轻松我们来看看如何使用日志记录来了解之前我展示的 Fruta app 中难以重现的程序错误我已经将日志记录添加进礼品卡视图的源代码了
我导入了 os 模块来访问日志记录 API 并创建了一个带有捆绑标识符和“礼品卡”分类的 logger 我添加了日志记录来记录这个视图下不寻常的事件比如当 app 开始了一项任务来与服务器通信时它现在会记录一个标识出任务的独特 UUID 由于标识符不包含敏感信息我将它设置为公开这样就在日志中可见了使用日志采集我已经将 Fruta app 中的日志提取到日志存档中了现在我会在控制台 app 中打开它
这里有很多日志条目这是因为日志存档包含了系统中所有进程记录的消息我可以使用控制台的“搜索”和“过滤”功能来缩小至我感兴趣的日志范围首先我会按子系统来过滤这个例子中就是我的 app 的捆绑标识符把显示范围限制为只有我的 Fruta app 内的消息
我会点击右上角的搜索框输入子系统
并在下拉列表中选中“子系统”
我可以只滚动浏览 app 的日志然后找到与失败相对应的消息
但由于我的 app 日志记录太多仍然有过多的条目让我无法了解其它地方出了什么问题我真正需要的是能缩小到问题范围的方法我的已记录任务标识符提供了解决方法（不在运行无法停止！）我可以用失败任务的任务标识符过滤来只看与失败相关的日志为此我现在要把任务标识符作为另一个关键词添加到搜索框内
现在剩下的日志比较少了我可以逐条查看并了解错误
第一个条目显示 app 正开始一项任务来获取更多礼品卡接着我看到由于一个网络错误任务已完成并且在超时后等待重试
下一个条目显示与此同时用户已经选中了一个礼品卡由此会试图将任务停止但由于此时没有正在进行的任务因此 app 发现自己处于不一致状态而导致失败
这就足以让我重新构建实际发生的情况了通过选中一张卡片我试图停止加载更多礼品卡的任务但恰恰在此之前它由于一个网络错误已经停止了这就解释了这个程序错误为何这么难重现因为它取决于事件和网络错误发生的先后时机多亏了日志我现在才能了解这个程序错误并修复它
我们看到通过使用“日志采集”命令你可以在 app 运行结束后采集日志你还可以在 app 运行中将日志进行流式传输如果你的设备连接了你的 Mac 你就可以在控制台 app 中实时进行日志消息的流式传输如果你的 app 是从 Xcode 启动的你也会在 Xcode 的控制台看到它们这是“printf”调试的有效替代方法它具有易于过滤的更加结构化的输出（日志级别）
你也许已经注意到当我在控制台 app 中浏览日志时 “失败”消息被特别标出了这是因为我用了“故障”日志级别来指示这条记录日志记录 API 提供了五个日志级别来指示消息的重要性
按照它们的重要性进行升序排列依次为调试信息、通知这也是默认级别错误和故障
“调试”级别只用在调试期间有用的消息上
“信息”级别用于对故障排除有用但并非关键的消息 “通知”指示的是对故障排除绝对关键的消息你可以使用“错误”级别来记录执行期间发生的错误 “故障”级别是最严重的你应该用它来记录程序中由于潜在程序错误而引发的情况比如记录在运行过程中违反了一个程序预期会保留的假设 “错误”和“故障”级别在控制台 app 中分别由黄色和红色气泡突出显示
logger 类型针对每个日志级别有不同方法比如要想记录一条调试消息要在 logger 上调用调试函数当选择日志级别时有一件很重要的事你必须考虑到那就是永久性意思是一条日志消息是否已归档及是否能在 app 执行结束后被取回不被保留的日志只能在 app 运行期间进行流式传输一条消息是否被保留由日志级别决定永久性与方法的重要性成正比
“调试”级别的消息不会被保留也就是说它们无法在 app 执行完成后被取回 “信息”错误的消息大部分不会被保留除非它们是在一条日志采集命令之前被生成记录为其它级别的消息都会被保留而且你之后可以取回它们不过归档消息的数量是有存储容量上限的一旦超过了上限旧消息就会被清除变为不可用 “错误”和“故障”级别的消息甚至会比“通知”级别的消息被保存得更久通常这些消息都会被保留数日不过这取决于你设备的存储容量
日志级别同样也影响到性能尽管日志记录一般开销很低但日志级别相对于彼此之间具备不同的性能重要性较低的级别速度更快 “故障”级别是最慢的而“调试”级别是性能最高的
记录“调试”级别的日志非常快因为调试消息都不会被保留它们在日志不进行流式传输时就会被丢弃此外 Swift 编译器使用复杂的优化来确保丢弃调试消息时甚至都不会执行创建消息的代码也就是说你可以在“调试”级别记录详尽的消息并且调用昂贵的函数来建立消息你的用户不用为它们买单（日志消息格式化）
正如我之前在 Fruta app 中展示的在一条日志消息中包含运行数据比如任务标识符会使它更有助于调试但是例如数字和字符串之类的原始数据就比较难以被了解和解读日志记录 API 为提高可读性提供了多种数据格式化方式而且无需消耗运行时间让我们再回到 Fruta app 来看看日志消息格式化是如何帮助调试的在礼品卡视图中我看到一个性能问题有时候卡片加载时间过长这个 app 使用了多个服务器来加载礼品卡我怀疑性能问题与选择的服务器有关为了对此进行调查我添加了一些日志记录来收集与服务器之间的通信统计信息
对于每一项任务我记录下任务标识符所获取礼品卡的标识符服务这项请求的服务器以及完成任务的总时长
现在我把我的 iPhone 连上我的 Mac 然后从 Xcode 运行 app 并在 Xcode 的控制台中查看日志
不幸的是由于日志排列不整齐所以很难理解它们我现在要使用格式化选项来让它们看起来更整齐
首先通过显示一个卡片标识符可以包含的最大字符数我固定了礼品卡标识符的宽度
我还把持续时间四舍五入到小数点后两位因为我并不需要太高的精确度
我现在重启 app 并再次查看日志
现在你能看到日志变得易读多了实际上由于它们非常整齐我甚至可以按住 option 键然后通过“选取列”来复制这些区域
我会将它们粘贴进 Numbers 表格并使数据可视化
通过这张图我能立即注意到速度慢的任务都经由服务器三所以我就要对这个服务器进行脱机维护
回顾一下你可以有选择地使用“格式化”和“对齐”参数来格式化数据由于格式化数据使用的日志记录 API 不会增加日志调用成本你可以尽情使用格式化功能来让你的数据看起来更美观易懂日志记录 API 提供了许多格式化选项我只为你展示了很少的几种
你可以用 Xcode 的代码补全来查看所有选项其中包括将数字格式化为十六进制八进制、指数以及更多选择
正如我们之前看到的你可以使用隐私选项来控制日志中的数据是否可见认真对待已记录数据的隐私非常重要因为日志记录随时都在发生甚至是在你的 app 发布并到达用户手中之后任何可以物理访问该设备且掌握密码的人都可以采集日志因此不在日志消息中将任何个人信息标记为公开十分重要否则就会在日志中被暴露
通过使用一个保留相等散列你可以获得许多与使用“公开”同样的好处但实际上却不用真的那么做这不会显示数据内容但仍然可以让你知道记录的数据什么时候是相同的从而有助于过滤日志
比如这里我要将一个 mask 参数传递给 .private 隐私选项以此来使用散列记录一位客户的银行账号这样在不显示银行账号的情况下就可以让我知道什么时候两条日志消息引用的是同一个账户
我所描述的 Logger API 可以在 iOS 14 上使用如果你的 app 针对先前的发行版本那么你可以使用 os_log 函数它接受 printf 样式的格式化字符串从这个发行版本开始字符串插值也可以被传递给 os_log 函数也就和使用 Logger 一样
总之你可以充分利用新的日志记录 API 以调试那些原本几乎不可能理解和修复的问题这个得以实现是因为你可以从你的开发设备上取回日志并对它们进行深入分析而无需重现一个程序错误日志记录 API 为你提供高性能的同时也提供了丰富的格式因此你可以记录包含有用信息的消息同时可以确信对于最终用户来说你的 app 不会变慢感谢观看

2:44 - Example illustrating how to add logging to your app in three simple steps

// Add logging to your app in three simple steps
 
import os

let logger = Logger(subsystem: "com.example.Fruta", category: "giftcards")

func beginTask(url: URL, handler: (Data) -> Void) {
    launchTask(with: url) {
       handler($0)
    }

    logger.log("Started a task")
}

3:32 - An example code that logs a message with run-time data

// Add runtime data to the log messsage using string interpolation

import os

let logger = Logger(subsystem: "com.example.Fruta", category: "giftcards")

func beginTask(url: URL, handler: (Data) -> Void) {
    launchTask(with: url) {
       handler($0)
    }
    logger.log("Started a task \(taskId)")
}

4:28 - Example illustrating why nonnumeric types are redacted in the logs by default
```
logger.log("Paid with bank account \(accountNumber)")
```
5:01 - Code that shows how to mark public data so that it is displayed in the logs
```
logger.log("Ordered smoothie \(smoothieName, privacy: .public)")
```

6:03 - Code shown during first demo

import SwiftUI
import os

let logger = Logger(subsystem: "com.example.Fruta", category: "giftcards")

struct GiftCardView: View {
    // Denotes whether there is an active task for loading gift cards.
    @State private var taskRunning: Bool = false
    
    // A UUID that uniquely identifies a task.
    @State private var currentTaskID: UUID = UUID()
    
    // An unrecoverable error seen during execution.
    @State private var error: Error? = nil

    // A model that stores information about gift cards.
    @ObservedObject var model: GiftCardModel
    
    var body: some View {
        // Display a list of gifts which can be tapped on and scrolled through.
        GiftCardList(model: model, taskRunning: $taskRunning, currentTaskID: $currentTaskID, error: $error, downloadAction: beginTask, stopAction: endTask)
            .navigationTitle("Gift Cards")
    }
    
    // Start a task to download gift cards from a server.
    func beginTask(serverURL: URL, cardDownloadHandler: @escaping (Data) -> Void) {
        logger.log("Starting a new task for loading cards \(currentTaskID, privacy: .public)")        
        launchTask(with: serverURL) {
            cardDownloadHandler($0)
        }
    }
    
    // Stop the currently running task for downloading cards from a server.
    func endTask() {
        guard taskRunning else {
            logger.fault("Task \(currentTaskID, privacy: .public) is not runinng, cannot be stopped!")
            error = TaskError.noActiveTask
            return
        }
        taskRunning = false
        logger.log("Task \(currentTaskID, privacy: .public) interrupted")
    }
    
    // Start a URLSession dataTask with the given URL.
    func launchTask(with url: URL, handler: @escaping (Data) -> Void) {
        guard error == nil else {
            return
        }
        taskRunning = true
        let task = URLSession.shared.dataTask(with: url) {
            data, response, error in
            if let error = error {
                self.error = ConnectionError.other(error)
            }
            if let data = data {
                handler(data)
            }
        }
        task.resume()
    }

}

11:51 - Illustration of how debug-level logging will not evaluate the code that constructs log message
```
logger.debug("\(slowFunction(data))")
```

12:58 - Code that shows how to display run-time data with a fixed width and how to set precision of a floating-point value using formatting options

import SwiftUI
import os

let statisticsLogger = Logger(subsystem: "com.example.Fruta", category: "statistics")

// Log statistics about communication with a server.
func logStatistics(taskID: UUID, giftCardID: String, serverID: Int, seconds: Double) {
    statisticsLogger.log("\(taskID) \(giftCardID, align: .left(columns: GiftCard.maxIDLength)) \(serverID) \(seconds, format: .fixed(precision: 2))")
}

15:00 - Example of formatting log messages

logger.log("\(data, format: .hex, align: .right(columns: width))")

16:05 - Example illustrating the use of a hash to redact private data, which ensures that identical data get the same hash
```
logger.log("Paid with bank account: \(accountNumber, privacy: .private(mask: .hash))")
```

正在查找特定内容？在上方输入一个主题，就能直接跳转到相应的精彩内容。

提交你查询的内容时出现错误。请检查互联网连接，然后再试一次。

资源

相关视频

WWDC23

WWDC20