应用程序开发中的日志级别：是什么、级别类型与配置方法

什么是日志级别？

日志级别（Log Level）——是每条日志消息的属性，用于确定其重要性和处理紧迫性。现代 iOS 和 Android 平台支持统一的 6–7 级分级体系：从最详细的级别（Verbose/Trace）到最关键的级别（Error/Assert）。级别的选择决定了在当前应用程序配置下消息是否会被写入日志。

日志级别的概念基于 严重性金字塔 原则：级别越高，在该级别显示的消息就越少。根据 Semaphore CI, 2024 的数据，在生产应用程序中，分布如下：Info — 60% 的消息，Warn — 25%，Error — 10%，Debug — 5%。Verbose 消息必须在生产环境中完全禁用。

每个平台都通过自己的 API 实现日志级别。Android 使用 android.util.Log，提供 v()、d()、i()、w()、e() 方法。Apple 使用 OSLog，提供 default、info、debug、error、fault 级别。像 Timber 和 CocoaLumberjack 这样的库在这些标准 API 之上构建了额外的功能。

根据 Google I/O 2023 的数据，日志级别选择不当是生产环境中 40% 性能问题的原因。开发人员将 Debug 日志保留在发布版本中，这会导致磁盘过度写入和电池加速耗尽。

日志级别的类型：从 Verbose 到 Assert

Verbose（TRACE）——最详细的级别，仅供开发使用。在此级别，所有中间计算、循环迭代、算法每一步的结果都被输出。在 Android 中，此级别对应 Log.v()，在 iOS 中对应类型为 debug 的 OSLog（在 iOS 14 之前使用 os_trace）。

Debug——调试消息，在开发和测试期间非常有用。包含关键对象状态信息、SQL 查询结果、API 调用参数。与 Verbose 不同，Debug 消息是结构化的且具有语义意义。在 iOS 中，此级别对应 OSLogType.debug。

Info——关于应用程序常规事件的信息性消息：SDK 初始化、成功认证、打开屏幕、从服务器接收数据。Info 消息 不得包含 用户的个人数据，并且必须对生产环境中的分析安全。在 iOS 中使用 OSLogType.info，在 Android 中使用 Log.i()。

Warn——关于潜在问题的警告。应用程序继续运行，但情况需要关注：缓存大小接近限制、API 版本过旧、网络响应缓慢、重新连接尝试。在 Android 中使用 Log.w()，在 iOS 中使用 OSLogType.default（用于警告）。

Error——严重错误，应用程序无法执行请求的操作但继续运行：API 请求失败、连接丢失、数据库写入错误、缺乏权限。在 iOS 中，错误使用 OSLogType.error，在 Android 中使用 Log.e()。

Assert（WTF）——最高级别，表示 “这种情况不可能发生” 的情况。用于记录违反系统基本不变量的错误。在 Android 中，Assert 消息默认不在发布版本中显示。在 iOS 中，WTF（What a Terrible Failure）通过 OSLogType.fault 处理。

在 Android 中使用日志级别

Android Log API——来自 android.util.Log 包的内置日志记录机制。提供 6 个静态方法：Log.v()、Log.d()、Log.i()、Log.w()、Log.e() 和 Log.wtf()。每个方法接受一个 tag（源标识字符串）和 msg（消息文本）。

class UserRepository {
    companion object {
        private val TAG = "UserRepo"
    }

    suspend fun loadUser(id: String): User {
        Log.d(TAG, "正在加载用户，id: $id")

        return try {
            val response = api.fetchUser(id)
            Log.i(TAG, "用户加载成功")
            response.toUser()
        } catch (e: Exception) {
            Log.e(TAG, "用户加载失败：${e.message}")
            throw e
        }
    }
}

按级别过滤在 Android Logcat 中通过 ADB 进行：adb logcat *:E 将只显示 Error 消息。在生产构建中，当启用混淆时，所有 Log.v() 和 Log.d() 调用都会被 ProGuard/R8 移除。Log.i()、Log.w() 和 Log.e() 保留，因此重要的是不要通过这些方法输出敏感数据。

对于运行时的自定义过滤，Android 提供了 Log.isLoggable(tag, level)——一种检查特定 tag 是否启用了指定级别的方法。这允许在不重新构建应用程序的情况下动态启用特定模块的详细日志记录。

在 iOS 和 macOS 中使用日志级别

OSLog——Apple 的统一日志记录系统，取代了已弃用的 NSLog。OSLog 提供 5 个级别：debug、info、default（notice）、error 和 fault。主要优势是 结构化日志记录，支持格式化字符串和通过控制台进行动态过滤。

import OSLog

let logger = Logger(
    subsystem: "com.example.app",
    category: "network"
)

func fetchData(from url: URL) {
    logger.debug("Starting request to \(url.absoluteString)")

    do {
        let data = try Data(contentsOf: url)
        logger.info("Received \(data.count) bytes")
    } catch {
        logger.error("Request failed: \(error.localizedDescription)")
    }
}

过滤系统OSLog 在操作系统级别工作。Debug 消息仅在调试器连接或启用参数 -com.apple.CoreData.Logging.debug 1 时写入。Info 消息存储在设备内存中（最多 512 KB），可通过 Console.app 访问。Error 和 fault 持续写入，可通过崩溃报告系统收集。

OSLog 的一个重要特性：带占位符的格式化字符串。与 Swift 字符串插值（无论级别如何，总是计算）不同，OSLog 使用 os_log 格式，通过 %{public}@ 和 %{private}@ 来区分敏感数据。私有参数在生产日志中被屏蔽。

生产环境 vs 调试：如何配置级别过滤

基本规则——生产环境中最小级别集合：Info、Warn、Error、Assert。Debug 和 Verbose 必须禁用。原因与其说是安全性，不如说是性能：每个日志调用都会消耗 CPU 时间来格式化字符串，即使消息不显示。

惰性字符串格式化

关键优化——切勿在日志调用中使用字符串插值。如果字符串在 log() 调用之前形成，即使级别已禁用，CPU 时间也会被浪费。通过 lambda 或守卫条件使用 惰性格式化。

在 Android 中，Log.isLoggable() 方法服务于这一目的；在 OSLog 中，是通过对带占位符的格式化字符串的原生支持。Android 的 Timber 通过 timber.log.Tree 在树内部进行级别检查来解决此问题。

运行时动态更改级别

远程日志级别（Remote Log Level）——一种实践，通过 Firebase Remote Config 或类似服务从服务器控制日志记录级别。如果生产环境中出现复杂错误，开发人员可以 远程启用特定模块的 Debug 日志记录，针对选定用户组的设备。

根据 Firebase, 2024 的数据，这种实践将罕见错误的诊断时间缩短了 60%，无需安装调试版本即可获得问题的完整图像。主要限制是日志仅在应用程序收到配置后的下一次启动时激活。

根据构建类型自动过滤

Android 中的 BuildConfig.DEBUG 和 Swift 中的 #if DEBUG——标准的条件编译机制，在发布版本中禁用调试级别。对于清晰的架构，建议将日志级别的选择提取到 DI 容器 或日志记录器工厂中，以避免业务逻辑被条件指令污染。

选择日志级别的最佳实践

第一条规则——每个日志调用都应回答 “谁、什么、何时” 的问题。谁——组件或模块（Android 中的 tag，iOS 中的 category）。什么——具体事件或状态变化。何时——时间戳，由日志系统自动设置。

第二条规则——不要通过 Info 及更高级别记录敏感数据。密码、令牌、电子邮件、电话号码、精确的地理坐标——在任何进入生产环境的日志中都严格禁止。必要时使用掩码处理：“email: us***@example.com”。

第三条规则——Warn 级别是开发人员的责任区域，Error 是团队的责任区域。Warn 意味着 “这里有潜在问题，注意观察”。Error 意味着 “这里有问题，需要修复”。不要将 Error 用于预期内并已处理的情况（例如 API 404 错误）。

第四条规则——一致性。整个项目应使用统一的标签和类别命名约定。建议 Android 标签使用 ClassName.methodName，iOS 类别使用 module.subsystem。这允许按组件快速过滤日志。

第五条规则——测试日志。在单元测试中检查在特定场景下是否调用了正确的日志级别。为此存在 模拟日志记录库：Android 的 Mockito，iOS 的 Cuckoo。在测试中检查级别可防止调试消息泄漏到生产环境中。