游戏客户端架构 / 系统课时

分级记录日志

分级记录日志

日志系统的价值不在于输出越多越好,而在于让不同严重程度的信息可筛选、可定位。本课将实现一个带 DEBUG、INFO、WARN、ERROR 四级过滤的线程安全日志器,并验证阈值如何控制实际输出。

学习目标

  • 理解四种常用日志级别的职责边界
  • 实现按最低级别过滤日志的基本机制
  • 避免多线程输出交错和级别滥用

先定义级别与过滤规则

日志级别应按严重程度递增。运行时设置一个最低输出级别,只有级别大于或等于阈值的消息才会被写出。

级别 适合记录 默认发布环境建议
DEBUG 帧数据、参数值、分支路径 通常关闭
INFO 初始化成功、场景切换、关键流程完成 保留
WARN 可恢复异常、性能下降、使用降级方案 保留
ERROR 当前操作失败、资源无法加载、不可继续的错误 保留

例如阈值设为 INFO 时,DEBUG 会被过滤,而其余三级正常输出。级别代表事件严重性,不代表开发者想让某条消息“更显眼”。

实现线程安全日志器

下面的 C++17 示例使用枚举表示级别、整数顺序完成过滤,并通过互斥锁避免多个线程同时写入时产生半行交错。

cpp
#include <iostream>
#include <mutex>
#include <string>

enum class LogLevel {
    Debug = 0,
    Info = 1,
    Warn = 2,
    Error = 3
};

const char* levelName(LogLevel level) {
    switch (level) {
        case LogLevel::Debug: return "DEBUG";
        case LogLevel::Info: return "INFO";
        case LogLevel::Warn: return "WARN";
        case LogLevel::Error: return "ERROR";
    }
    return "UNKNOWN";
}

class Logger {
public:
    explicit Logger(LogLevel threshold)
        : threshold_(threshold) {}

    void log(LogLevel level, const std::string& message) {
        if (level < threshold_) {
            return;
        }

        // 一次持锁写完整行,防止并发日志互相穿插。
        std::lock_guard<std::mutex> lock(outputMutex_);
        std::cout << "[" << levelName(level) << "] "
                  << message << std::endl;
    }

private:
    LogLevel threshold_;
    std::mutex outputMutex_;
};

int main() {
    Logger logger(LogLevel::Info);

    logger.log(LogLevel::Debug, "Mouse position: 120, 64");
    logger.log(LogLevel::Info, "Audio device initialized");
    logger.log(LogLevel::Warn, "FPS dropped below target");
    logger.log(LogLevel::Error, "Failed to load ui/button.png");
}

预期输出

text
[INFO] Audio device initialized
[WARN] FPS dropped below target
[ERROR] Failed to load ui/button.png

第一条 DEBUG 消息没有出现在结果中,因为当前阈值是 INFO。把构造参数改为 LogLevel::Debug 后,四条消息都会输出。

把日志放在正确位置

DEBUG 应记录仅在定位问题时需要的细节,例如碰撞检测输入、资源查找路径或状态机转移。INFO 用于确认系统完成了重要但正常的动作,例如渲染器初始化成功。

WARN 表示系统仍能继续运行,但结果可能降级,例如音频设备不可用后切换为静音模式。ERROR 表示某次操作已经失败,应包含失败对象和必要上下文,而不是只写“发生错误”。

不要在每帧无条件输出大量日志。高频路径即使被过滤,也可能先完成字符串拼接并造成额外开销;后续可通过延迟格式化或编译期裁剪降低成本。

验证与常见错误

验证过滤时,可依次把阈值设为 DEBUG、INFO、WARN 和 ERROR,确认可见消息范围逐级缩小。若发布版本仍出现大量帧级日志,说明调用点或默认阈值设置不合理。

常见错误包括把可恢复情况记录为 ERROR、错误消息缺少资源名或状态值,以及多个线程直接写控制台却没有同步。日志必须帮助定位问题,不能只重复“失败了”这一事实。

本课总结

  • 日志阈值决定最低可见级别,严重程度越高越不应被过滤
  • 四种级别分别服务于调试细节、正常流程、可恢复异常和操作失败
  • 多线程日志需要保证整行原子写出,高频日志还要关注格式化成本

下一课预告

下一课将为日志补充时间、源码位置和文件输出,并设计可替换的控制台与文件写入目标。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

分级记录日志

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通