游戏客户端架构 / 系统课时
分级记录日志
分级记录日志
日志系统的价值不在于输出越多越好,而在于让不同严重程度的信息可筛选、可定位。本课将实现一个带 DEBUG、INFO、WARN、ERROR 四级过滤的线程安全日志器,并验证阈值如何控制实际输出。
学习目标
- 理解四种常用日志级别的职责边界
- 实现按最低级别过滤日志的基本机制
- 避免多线程输出交错和级别滥用
先定义级别与过滤规则
日志级别应按严重程度递增。运行时设置一个最低输出级别,只有级别大于或等于阈值的消息才会被写出。
| 级别 | 适合记录 | 默认发布环境建议 |
|---|---|---|
DEBUG |
帧数据、参数值、分支路径 | 通常关闭 |
INFO |
初始化成功、场景切换、关键流程完成 | 保留 |
WARN |
可恢复异常、性能下降、使用降级方案 | 保留 |
ERROR |
当前操作失败、资源无法加载、不可继续的错误 | 保留 |
例如阈值设为 INFO 时,DEBUG 会被过滤,而其余三级正常输出。级别代表事件严重性,不代表开发者想让某条消息“更显眼”。
实现线程安全日志器
下面的 C++17 示例使用枚举表示级别、整数顺序完成过滤,并通过互斥锁避免多个线程同时写入时产生半行交错。
#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");
}预期输出
[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、错误消息缺少资源名或状态值,以及多个线程直接写控制台却没有同步。日志必须帮助定位问题,不能只重复“失败了”这一事实。
本课总结
- 日志阈值决定最低可见级别,严重程度越高越不应被过滤
- 四种级别分别服务于调试细节、正常流程、可恢复异常和操作失败
- 多线程日志需要保证整行原子写出,高频日志还要关注格式化成本
下一课预告
下一课将为日志补充时间、源码位置和文件输出,并设计可替换的控制台与文件写入目标。