游戏客户端架构 / 系统课时
怎样建立统一日志等级
怎样建立统一日志等级
统一日志等级不是给消息贴标签,而是让开发、测试和线上诊断对“严重程度”形成同一套判断。设计得当后,开发期能保留足够细节,线上又不会被大量无价值日志淹没,真正的异常也能被稳定检索和告警。
学习目标
- 明确 Debug、Info、Warning、Error、Fatal 的使用边界
- 用统一规则决定一条日志应该属于哪个等级
- 通过最小实现验证等级过滤是否符合预期
先按“系统还能否正常继续”分级
最实用的判断顺序不是看文字听起来多严重,而是看事件对当前功能和进程的影响。只要团队始终按影响判断,同一类问题就不会有人写成 Info、有人又写成 Error。
| 等级 | 适合记录什么 | 典型边界 |
|---|---|---|
| Debug | 高频内部状态、临时诊断细节 | 不应默认长期全量开启在线上 |
| Info | 正常但有诊断价值的关键里程碑 | 不记录每帧、每次轮询等高频事件 |
| Warning | 出现异常,但已有降级、重试或兜底 | 当前流程仍能继续 |
| Error | 当前操作失败,需要调查 | 进程或会话仍可继续 |
| Fatal | 状态已不可安全恢复 | 通常意味着会话或进程即将终止 |
例如“资源第一次读取失败,但随后从备用地址加载成功”更适合 Warning;“本次资源加载最终失败,场景无法继续”应记为 Error;只有客户端已经进入不可恢复状态时,才使用 Fatal。
让等级同时控制输出范围
统一等级还必须配合过滤策略,否则只是换了五个标签。下面用一个最小 C# 程序演示:运行环境把最低等级设置为 Info 后,Debug 会被过滤,其余更高等级继续输出。
using System;
enum LogLevel
{
Debug = 10,
Info = 20,
Warning = 30,
Error = 40,
Fatal = 50
}
static class Logger
{
public static LogLevel MinimumLevel { get; set; } = LogLevel.Info;
public static void Log(LogLevel level, string message)
{
// 统一在出口做等级过滤,避免各业务模块自行判断。
if (level < MinimumLevel)
{
return;
}
Console.WriteLine($"[{level}] {message}");
}
}
class Program
{
static void Main()
{
Logger.MinimumLevel = LogLevel.Info;
Logger.Log(LogLevel.Debug, "frame cache hit");
Logger.Log(LogLevel.Info, "entered lobby");
Logger.Log(LogLevel.Warning, "primary endpoint failed, fallback succeeded");
Logger.Log(LogLevel.Error, "profile save failed");
Logger.Log(LogLevel.Fatal, "runtime state corrupted, client must exit");
}
}预期输出:
[Info] entered lobby
[Warning] primary endpoint failed, fallback succeeded
[Error] profile save failed
[Fatal] runtime state corrupted, client must exit真实项目可以把同样的判断放进 Unity、Unreal 或自研引擎的日志封装层,再把输出接到控制台、文件、远程日志或崩溃采集系统。关键不是复制这段代码,而是保证所有模块只通过同一个入口执行等级过滤。
给每个等级设可执行的团队规则
规则要能让不同开发者面对同一事件时做出接近的选择。最简单的方法是先问三个问题:这是正常路径吗;当前操作是否失败;失败后系统是否还能安全继续。
正常且值得追踪的关键节点写 Info;只为定位内部细节、且可能高频出现的内容写 Debug;发生偏差但被兜底成功写 Warning;本次操作已经失败写 Error;客户端无法安全继续时才写 Fatal。
日志等级之外还要统一事件名称、会话标识、构建版本和关键上下文字段。否则即使等级正确,线上出现一次 Error 时仍无法把前后的相关事件串起来。
控制噪声而不是简单“少打日志”
降低日志量不等于删除证据。优先处理重复且高频的信息,例如每帧状态、固定周期心跳成功、循环中的相同失败。它们更适合采样、聚合或仅在 Debug 模式下开启。
相反,进入关键场景、配置加载结果、网络重连开始与结束、资源回退、持久化失败等事件,即使发生频率不高,也应保留足以还原过程的 Info、Warning 或 Error。这样日志既不会失控,又能在故障发生后提供连续上下文。
最终标准很简单:看到一个等级时,工程师应能立刻判断“这是正常轨迹、已兜底异常、操作失败,还是不可恢复故障”,而不需要先猜作者当时的情绪。